LaunchInstance

Use this resource to start a new work instance from an application definition.

Method summary

HTTP Method Path Description
POST /scr/api/LaunchInstance Starts a new work instance from an application definition.

POST /scr/api/LaunchInstance

Description
Use this method to start a new work instance from an application definition.
Resource information
Requirements Description
Response format JSON
Requires authentication Yes
Supports OAuth 2 client credentials Yes using a User Service ID containing Work Management Category
Rate limited Not yet
Parameters
Name Location Description Required Type
X-On-Behalf-Of Header The user context. The value must be a username in the account. The user must have permission to perform the action in the account and in the specified parent space, if any. Required if Service ID OAuth credentials are used. Not required when using User Service ID OAuth credential. String
instance Query The definition for the instance to create. The instance format is shown in the example. Yes See Instance parameters below
version Query The version of the requested API. The only allowed value is 20110917. Yes String
Instance parameters
Name Location Description Required Type
app.attachments Query The array of attachments to associate with this instance. These attachments can be either originally attached to the application definition, or they might be newly created just for this instance. Each attachment is identified by its ID; the ID information can be retrieved from the AppDetails attachments array or returned from a file upload call. Provide an empty array if you are not attaching files. Yes JSON array of attachments
app.attachments.id Query The ID of the attachment. Yes, if an attachment is provided String
app.id Query The ID of the application. Yes String
app.subject Query The subject for the new work instance. Yes String
app.tasks Query The array of tasks associated with the instance. This task can be either an existing one from an AppDetails response, in which case the ID property must be provided, or a new task without an ID parameter. Yes JSON array of tasks k
app.tasks.assignedTo Query The ID of the user to whom the task is assigned. Yes String
app.tasks.id Query The ID of the task. You must provide the ID for a task that is a part of the application definition. You don't need to provide the ID for a new task. Yes, unless it's a new task String
app.tasks.name Query The name of the task. Yes String
app.details Query The details for the new work instance. No String
app.mailOnCompletion Query The notification email setting. Set to true to send a notification email when the work item is completed, or set to false to omit sending an email. No Boolean
app.tasks.approvalStep Query Set the value to true for an approval step, and omit the parameter or set the value to false for a step that is not an approval. No Boolean
app.tasks.dueDateExpression Query The expression that specifies the due date must be in the following format: yyyy/mm/dd. No String
app.timeZoneId Query The timezone to start the instance in. If the timezone is not provided, then the value from the user's current preferences is used. If user's timezone preference is also not set, then the server default is used. No String
Response
Example input
  • Using User Service ID OAuth 2 client credentials:
    curl -i -X POST 
  'https://your_server_url/scr/api/LaunchInstance?version=20110917' 
  --data-urlencode 'instance={"app":{"subject":"New for test.","id":"5f500e12a00ee","details":"my sample details","mailOnCompletion":false,"tasks":[{"name":"task1","id":"5f501e134ae2f","assignedTo":"7f0002","approvalStep":false}],"attachments":[]}}' 
  --header 'Accept: application/json' 
  --header 'Authorization: Bearer access_token'
  • Using Service ID OAuth 2 client credentials:
    curl -i -X POST 
  'https://your_server_url/scr/api/LaunchInstance?version=20110917' 
  --data-urlencode 'instance={"app":{"subject":"New for test.","id":"5f500e12a00ee","details":"my sample details","mailOnCompletion":false,"tasks":[{"name":"task1","id":"5f501e134ae2f","assignedTo":"7f0002","approvalStep":false}],"attachments":[]}}' 
  --header 'Accept: application/json' 
  --header 'X-On-Behalf-Of:user_name@domain.com' 
  --header 'Authorization: Bearer access_token'
Example output
{  
   "work":{  
      "runtimeVersion":[  
         "ede1c9df-61be-4774-99ab-196ec6742d57",
         "5f501e134ae25",
         1
      ],
      "details":"my sample details",
      "canManageWork":true,
      "name":"ProcessApp with multiple tasks A - New for test.",
      "subject":"New for test.",
      "tasks":[  
         {  
            "status":"NotStarted",
            "assignedTo":"7f0002",
            "name":"task 1",
            "id":"5f501e134ae2f",
            "approvalStep":false
         }
      ],
      "attachments":[  

      ],
      "status":"Active",
      "comments":[  

      ],
      "startedAt":1441218212876,
      "startedBy":"7f0002",
      "id":"5f501e134ae25",
      "appId":"5f500e12a00ee"
   },
   "app":{  
      "detailsTitle":null,
      "type":"workflow",
      "name":"ProcessApp with multiple tasks A",
      "id":"5f500e12a00ee",
      "subjectTitle":null
   },
   "version":"20110917",
   "users":[  
      {  
         "avatarId":"5f500e1260203",
         "name":"admin",
         "id":"7f0002"
      }
   ]
}
Response properties
version
The version of the API used to create the response.
work
The work object.
work.runtimeVersion
The array that identifies the version of the work instance. Treat this value as an opaque data item. The work.runtimeVersion is required for the WorkAction.
work.name
The name to display for the work instance.
work.id
The ID of the work instance.
work.subject
The subject entered by the user who created the instance.
work.details
The details entered by the user who created the instance.
work.status
The status of work includes one of the following values:
  • Active
  • Completed
  • Cancelled
  • Overdue
work.startedBy
The ID of the user who created the instance. An object with this ID appears in the user's array.
work.startedAt
The date and time when the instance was started. The value is expressed in milliseconds since epoch, that is 1 January 1970 at midnight Coordinated Universal Time (UTC).
work.completedBy
The ID of the user who completed or canceled the instance. Only present if the status is Completed or Cancelled. An object with this ID appears in the user's array.
work.completedAt
The date and time when the instance was completed or canceled. The value is expressed in milliseconds since epoch, that is 1 January 1970 at midnight Coordinated Universal Time (UTC). Only present if the status is Completed or Cancelled.
work.appId
The ID of application from which the instance was started. This application appears in the application object.
work.canManageWork
Indicates whether the user has permissions to cancel work, change subject, or reassign tasks.
work.tasks
The array of tasks associated with the instance.
work.tasks.name
The name of the task.
work.tasks.id
The ID of the task.
work.tasks.assignedTo
The ID of user to whom the task is assigned. An object with this ID appears in the user's array.
work.tasks.actioner
The ID of the user who is not the task owner and who created the last change in the task status. An object with this ID appears in the user's array. When a task is reassigned, the work.tasks.actioner refers to the ID of the user who did the reassigning, while the assignedTo user is the user to whom the task was originally assigned.
work.tasks.dueDate
The date when the task is due. This property is present only if a dueDate is set for the task.
work.tasks.status
Contains one of the following possible values:
  • Pending
  • NotStarted
  • InProgress
  • Completed
  • Reassigned
work.tasks.reassignmentReason
This property is present only if the status is Reassigned. Contains one of the following possible values:
  • TaskReassigned
  • OwnerDowngraded
  • OwnerArchived
work.tasks.approvalStep
The value is either true or false.
work.tasks.isApproved
If the task is an approval step, that is approvalStep is true, and the task is completed, that is the status value is Completed, then isApproved is present, and the value is true or false.
work.attachments
The array of attachments associated with the instance or the application it was started from.
work.attachments.name
The name of the attachment.
work.attachments.id
The ID of the attachment.
work.attachments.uploadedBy
The ID of the user who uploaded the attachment. An object with this ID appears in the users array.
work.attachments.uploadedOn
The date and time when the attachment was uploaded. The value is expressed in milliseconds since epoch, that is 1 January 1970 at midnight Coordinated Universal Time (UTC).
work.attachments.size
The size of the attachment in bytes.
work.attachments.type
The type of attachment file with the associated numeric value.
Attachment type Description
1 Generic document. Used if the file doesn't fall under one of the other values.
2 Microsoft Excel file
3 Image
4 PDF document
5 Microsoft PowerPoint document
6 Microsoft Project document
7 Microsoft Visio document
8 Microsoft Word document
work.attachments.canDelete
Indicates whether the user has permissions to delete the attachment.
work.attachments.deletedOn
The date and time when the attachment was deleted. The value is expressed in milliseconds since epoch, that is 1 January 1970 at midnight Coordinated Universal Time (UTC). This field is present only if the file was deleted from the account through the admin pages. In this case, you can't download the file using FileDownload.
work.attachments.deletedBy
The name of the user who deleted the attachment. This field is present only if the file was deleted from the account through the admin pages.
work.comments
The array of comments on the instance.
work.comments.from
The ID of the user who created the comment. An object with this ID appears in the user's array.
work.comments.id
The ID of the comment.
work.comments.commentDate
The date when the comment was created.
work.comments.text
The text of the comment.
work.comments.canDelete
Indicates whether the user can delete the comment.
work.comments.replies
The list of replies to the parent comment.
app
The information about the application that the instance was started from.
app.name
The name of the application that the work instance was started from.
app.id
The ID of the application from that the work instance was started from.
app.subjectTitle
The title for edit area where the user entered a subject for the instance.
app.detailsTitle
The title for edit area where the user entered details for the instance.
app.type
The type of the application that contains one of the following possible values:
  • workflow
  • checklist
users
The array of users whose IDs are referenced from other locations in the JSON.
users.name
The full name of the user.
users.id
The ID of the user.
users.avatarId
The ID of the avatar the user set. This property is present only if the user set an avatar.
Response messages
HTTP code Reason
200

The request was completed successfully.
400

There is an error processing the request. Required parameters were missing or contained invalid values.
401

The user isn't authorized to make the request.