jobs/{id}/summary

Gets basic summary information for the job as well as the list of actions permitted for the current user

This method is useful to implement tools to quickly view the status of a job and propose all available actions to the user:

  • Accept job or proposal
  • Decline job
  • Re-assign job
  • Manager only actions where applicable
  • Etc.

 

URL

(GET) /jobs/{id}/summary

PARAMETERS

URL parameters are:

id

The job ID. Formats used are:

  • "c{number}" : A Codyt job. Examples: c3302, c102...
  • "s{number}" : A Standard job. Examples: s223, s994
Mandatory


RESULTS

The result is a JSON object:

idThe globally unique string ID of the job, such as "c2002" or "s773"string
jobidThe numeric job id (unique for Standard and Codyt respectively)int
iscodytTrue: A Codyt job. False: A standard job.bool
referenceThe reference of the job. With Codyt jobs this is the job's document name.string
src / srctSource language code and namestring
trg / trgtTarget language code and namestring
branch / branchtBranch language code and name. In general the branch locale is identical to the target locale. It may be different where a workflow involves a back translation or translation into pivot languages.string
task / tasktType of task with code and title. 
pnameThe reference of the project.string
pidThe project id.int
statusThe job status as a number. See Job Statusint
statustThe job status name.string
hasPredecessorTrue if this job has a predecessor in the workflowbool
   
assignment

A node containing details on the current job assignment, see further down.

Example:

"assignment": {
    "mode": 0,
    "modet": "Fixed assignment",
    "cid": 334,
    "cname": "Ultra Translations",
    "uid": null,
    "uname": null,
    "wasAccepted": true
  }
 
   
deadlineDeadlinedatetime?
dtstartDate when the job started (typically when moved to in progress status).datetime?
dtendDate when the job was finished (when moved to completed or above status).datetime?
dtcassignDate when the company was assigned.datetime?
dtpassignDate when the person was assigned.datetime?
   
actions

An array of available actions, see below.

If no action is available to the user, the array is empty.

Example:

{
    "id": "OPENING_ACCEPT_INACTIVE",
    "title": "Yes, I want to reserve this upcoming job!",
    "desc": "This job is still inactive but you can already reserve it now.",
    "isinfo": false,
    "isprimary": true,
    "affectsRights": true,
    "style": "Green",
    "uicontrol": "TermsShowLink"
  }
object[]
readOnlyFor information. If false then the job is totally locked for any change. This is for example the case if the parent project has been closed.bool
uicontrolsAn object that includes additional parameters per actions' "uicontrol" value. These are properties required to render the action specific UI.object

 

Assignment object

The object has these properties:

mode

0 = fixed assignment mode, 1 = open job proposal, 2 = crowd sourcing mode

int 
modet The name of the mode. Example: "Fixed assignment" string
cid

Null or the ID of the assigned company.

Note that if mode = 1, a job is still a proposal and never assigned yet.

If mode = 2, the job is not assigned neither since multiple people can work at the same time.

int?
cnameNull or the name of the assigned company.string?
uid

Null or the ID of the assigned person. If this value is set then "cid" is set as well.

Note that a job can be assigned to just a company without specifying a specific user. The exception is, of course, if a job is assigned to an in-house worker.

int?
uname

Null or the name of the assigned person.

To get full person details, use: persons/{uid}

string?
wasAccepted

When a job is assigned by a manager, this property is false. It is set to true as soon as the assigned company or person takes action such as: Accept job, Accept job proposal, Change status to In Progress, etc.

This flag is a useful indication for the manager as well as the assigned worker.

bool

 

Action object

Each element in actions has these properties:

idThe ID of the action. When you want to apply an action you will need to supply this ID.string
titleThe name or title of the action.string
descNull or a description of the action.string?
isinfo

True if this item is only there to show some information. No button.

This is for example used when there is no action available to the user and we want to inform the user why there is no action at this point in time.

bool
isprimary

True if this action should be shown prominently. Typically all primary actions should be immediately accessible through buttons and without opening a combo etc.

False if this action is less important and can be hidden in an "Actions" drop down.

bool

affectsRights

Indicates if applying the action will change the accessibility of the job.

For example, changing the status of a job requires reloading editing access rights with parameter "loadRightsFromCache" = true in the editor initialisation method: resources/segments/view/properties

One of the actions giving "false" for this property is the one to submit a message with the job.

 
style

A color style for actions. For example, cancellation may be colored "red", job acceptance be colored "green" and so on.

Possible values are:

  • Default - Regular color (black)
  • Green - Actions like for accepting new jobs or completing work
  • Orange - Actions such as refusals
  • Red - Actions such as cancellations
  • Gray - Actions that are less used such as re-assigning to a colleague
string
uicontrol

This defines what you need to show to the user together with the title and description of the action:

  • None - A simple button to run the action
  • Terms - Show terms & conditions (either link to read or also the checkbox - depending on other properties)
  • KeepJobOpen - Control to ask if the current job shall be left open when sending back to previous job
  • AssignWithinCompany - Exposes control to let user choose another person within his/her company
  • WorkCompleted - Check if all work is done (stats, no errors, etc.).

 

NOTE: If isinfo is true then uicontrol will be

string
mustNotify

If true, a notification will be sent always. The user has no possibility to untick the notify checkbox.

Any unticking will be overridden server side.

bool

 

Uicontrols object

The object has one property per UI control in the list of actions. If there is no action at all, the object is empty (but not null).

 

NoneAlways nullobject
Terms

Contains properties:

  • termsShow: True if you need to render a checkbox to accept terms & conditions + a link to view the terms. If false then this panel is not shown.

To fetch terms & conditions use this API: jobs/{id}/terms/preview (without setting the cid/pid parameters)

object
KeepJobOpen

Always null.

Render a checkbox, unticked by default, and ask the user if the job shall be kept open when sending back work to the preceding job in the workflow.

object
AssignWithinCompany

Always null.

Use API to get list of colleagues of the current user.

object
WorkCompleted

Contains properties:

  • canSkip: If true, the user can complete the job even if the stats are "bad" (QA errors...). True if user has advanced management rights.

 

To evaluate if the job has problems, use this API method:

jobs/{id}/terms/checklist

If the pass result is false, the job cannot be completed - Unless canSkip above is true.

Users with advanced access rights can override blocking situations:

 

 

 

EXAMPLES

The following example is for a manager user accessing a job which is proposed to him/her. As a manager, the user has management level actions as well.

{
  "id": "c231",
  "jobid": 231,
  "iscodyt": true,
  "status": 1,
  "statust": "Not assigned",
  "hasPredecessor": false,
  "assignment": {
    "mode": 0,
    "modet": "Fixed assignment",
    "cid": null,
    "cname": null,
    "uid": null,
    "uname": null,
    "wasAccepted": false
  },
  "readOnly": false,
  "actions": [
	  {
		"id": "OPENING_ACCEPT_INACTIVE",
		"title": "Yes, I want to reserve this upcoming job!",
		"desc": "This job is still inactive but you can already reserve it now. This will put your name on the job.",
		"isinfo": false,
		"isprimary": true,
        "affectsRights": true,
		"style": "Green",
		"uicontrol": "Terms"
	  },
	  {
		"id": "OPENING_DECLINE",
		"title": "Unfortunately, I have to decline this proposal.",
		"desc": "This will remove the job opening from your job list.",
		"isinfo": false,
		"isprimary": true,
        "affectsRights": true,
		"style": "Gray",
		"uicontrol": "None"
	  },
	  {
		"id": "ADMIN_STATUS_NOTASSIGNED",
		"title": "Change status to 'Not assigned'",
		"desc": null,
		"isinfo": false,
		"isprimary": false,
        "affectsRights": true,
		"style": "Default",
		"uicontrol": "None"
	  },
	  {
		"id": "ADMIN_STATUS_NOTSTARTED",
		"title": "Change status to 'Not started'",
		"desc": null,
		"isinfo": false,
		"isprimary": false,
        "affectsRights": true,
        "style": "Default",
		"uicontrol": "None"
	  }
	],
  "uicontrols": {
    "Terms": { "termsShow": true },
    "None": null
  },
}

 

 

 

 

Copyright Wordbee - Buzzin' Outside the Box since 2008