Action Create

Non-standard resource

Note: This is a non-standard resource and does not implement all the same functionality as a regular resource. The GET and POST requests do not have the same structure and do not return the same result.

Please read the documentation for this resource carefully.


Creating an action is a variable request depending on how the "Start" step is configured in the action type you are trying to create an action for. For example, creating an action for an action type with no user-input required on the start step is pretty easy, where-as an action type with a very long set of user input fields will require a very complex API request.

There are two common scenarios for creating an action via this API resource; creating a known action type (where you could hard-code the request) or a generic application where you must discover the structure of the start step, then ask the user for input, then build the API request.


Resource Properties
Scope Parameteractioncreate
Location/actioncreate
MethodsGET, POST
Default Page Size50
Max Page Size200
Default Includesstep, stepTasks, stepMessages, documentTemplates, stepParticipantTypes, otherParticipantTypes, stepDataFields, stepRelatedActionTypes and trustAccounts


GET requests

The GET request for the actioncreate resource will return a set of resources which you must complete for the POST request. For example, you may get a list of "stepTasks" which contain a list of tasks (some optional) which the user must see (and confirm/unselect if task is optional).

The request structure is: GET /api/rest/actioncreate/{action-type-id}

 The GET request does not support filters or multiple resource identifiers. It only supports a single resource id (the action-type-id you want to create). This is due to the complexity of the resource.


GET Resource Attributes
FieldDescriptionFormatField TypeNotes
idAction Type IDstringdefault
stepLink to the "Start" step being describedstringlink
stepTasksList of all the tasks (both required + optional) for this stepcollectionlink
stepMessagesList of all the messages to be sent (currently limited to emails) for this stepcollectionlink
documentTemplatesList of all the document templates to be added to the action for this stepcollectionlink
stepParticipantTypesList of all the participant types specifically requested to be displayed to the user for this stepcollectionlink
otherParticipantTypesList of participant types (other than those in stepParticipantTypes) that should be shown to the user due to their inclusion in an email etccollectionlink
stepDataFieldsList of data-fields that should be editable by the user for this stepcollectionlink
stepRelatedActionTypesList of related action types that are required for the user to associate on this stepcollectionlink
actionType
stringlink
trustAccountsList of trust accountscollectionlink


Link Templates
IdentifierResourceLocation Template
actioncreate.stepstep/step/{actioncreate.step}
actioncreate.stepTaskssteptasks/steptasks/{actioncreate.stepTasks}
actioncreate.stepMessagesstepmessages/stepmessages/{actioncreate.stepMessages}
actioncreate.documentTemplatesdocumenttemplates/documenttemplates/{actioncreate.documentTemplates}
actioncreate.stepParticipantTypesstepparticipanttypes/stepparticipanttypes/{actioncreate.stepParticipantTypes}
actioncreate.otherParticipantTypesparticipanttypes/participanttypes/{actioncreate.otherParticipantTypes}
actioncreate.stepDataFieldsstepdatafields/stepdatafields/{actioncreate.stepDataFields}
actioncreate.stepRelatedActionTypessteprelatedactiontypes /steprelatedactiontypes/{actioncreate.stepRelatedActionTypes}
actioncreate.actionTypeactiontypes/actiontypes/{actioncreate.actionType}
actioncreate.trustAccountstrustbankaccounts/trustbankaccounts/{actioncreate.trustAccounts}


POST Requests

Unlike a regular resource, the POST request format is different to the GET request as you are not saving the step configuration, instead you are submitting the data entered by the user in relation to the step configuration.

The best way to understand a POST request is to configure your start step in Actionstep then create an action using the Actionstep user-interface. There you will see all the user-input fields that we display to the user to create an action of that type. In order for the API to create the same action, we require all that data to be specified in the POST request using a format that is consistent with our standard API data structures.

Note: the response to a POST request is the standard "actions" GET response (but under "actioncreate" instead). This is non-standard as the standard GET response for actioncreate would make no sense after a POST request.


POST Resource Attributes
FieldDescriptionFormatRequiredField TypeNotes
actionNameThe name of the new action being createdstringtruedefault
fileReferencethe file reference of the new actionstringfalsedefault
prioritythe priority of the new actionintegerfalsedefault
statusThe status of the new ActionstringfalsedefaultDefaults to Active, options are Active, Inactive, Template or Closed
timestampThe date/time to set as the step-change datedatefalsedefaultDefaults to now.
stepDataField{N}

Values for each step data field. (may be many occurrences of this attribute).
Note, that {N} is for each of the {stepDataFields}.{id} that are specified in the GET request

mixedtruedefaultFields not specified will be updated to NULL if the field is optional.
fileNoteFile-note text to be added as a step-change file notestringsometimesdefaultIs required when the step configuration requires a file note.
actionTypeThe ID (Action type id) of the type of action being created.stringtruelink
assignedToParticipantwho the new action is assigned to (defaults to the current user)stringfalselinkDefaults to the access token's participant if not specified
stepTasks

List of the {stepTasks}.{id} that the user confirmed they want to create.
Any missing ID implies the user deselected the task.
The list of available {stepTasks}.{id} is set in the GET response 

collectionfalselinkMandatory tasks will always be created regardless of them being specified or not.
Make sure to check there are participants specified for the task's assigned to participant type. 
stepMessages

List of {stepMessages}.{id} that the user confirmed they want to create.
Any missing ID implies the user deselected the message. 
The list of available {stepMessages}.{id} is set in the GET response 

collectionfalselinkMandatory messages will always be created regardless of them being specified or not.
Make sure to check there are participants specified for the messages to/from are specified.
Also check those participants have a valid email address if the message is an email. 
documentTemplatesList of {documentTemplates}.{id} that the user confirmed they want to create.
Any missing ID implies the user deselected the template.
The list of available {documentTemplates}.{id} is set in the GET response 
collectionfalselink
participantType{N}List of participants for each participant type. (may be many occurrences of this attribute).
Note that {N} is for each of the {stepParticipantType}.{participantType} or {otherParticipantTypes}.{id} listed in the GET response.
collectionfalselink
relatedActionType{N}List of actions for each action type. (may be many occurrences of this attribute).
Note that {N} is for each of the {stepRelatedActionTypes}.{id} listed in the GET response.
collectionfalselink
trustAccouns{N}List of trust bank accountscollectionfalselink


The error reporting for this resource is a little sparse at the moment, so please email us at api@actionstep.com if you have any trouble using this resource.

Example:

In this example, we'll create an action which has a lot of information configured.

Create Action - Complex GET
GET /api/rest/actioncreate/42
{
	"links": {
		"actioncreate.step": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/steps\/{actioncreate.step}",
			"type": "steps"
		},
		"actioncreate.stepTasks": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/steptasks\/{actioncreate.stepTasks}",
			"type": "steptasks"
		},
		"actioncreate.stepMessages": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/stepmessages\/{actioncreate.stepMessages}",
			"type": "stepmessages"
		},
		"actioncreate.documentTemplates": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/documenttemplates\/{actioncreate.documentTemplates}",
			"type": "documenttemplates"
		},
		"actioncreate.stepParticipantTypes": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/stepparticipanttypes\/{actioncreate.stepParticipantTypes}",
			"type": "stepparticipanttypes"
		},
		"actioncreate.otherParticipantTypes": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/participanttypes\/{actioncreate.otherParticipantTypes}",
			"type": "participanttypes"
		},
		"actioncreate.stepDataFields": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/stepdatafields\/{actioncreate.stepDataFields}",
			"type": "stepdatafields"
		},
		"actioncreate.stepRelatedActionTypes": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/steprelatedactiontypes\/{actioncreate.stepRelatedActionTypes}",
			"type": "steprelatedactiontypes"
		},
		"steps.actionType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/actiontypes\/{steps.actionType}",
			"type": "actiontypes"
		},
		"steps.assignToParticipantType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/participanttypes\/{steps.assignToParticipantType}",
			"type": "participanttypes"
		},
		"steptasks.actionType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/actiontypes\/{steptasks.actionType}",
			"type": "actiontypes"
		},
		"steptasks.assignToParticipantType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/participanttypes\/{steptasks.assignToParticipantType}",
			"type": "participanttypes"
		},
		"steptasks.step": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/steps\/{steptasks.step}",
			"type": "steps"
		},
		"stepmessages.actionType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/actiontypes\/{stepmessages.actionType}",
			"type": "actiontypes"
		},
		"stepmessages.step": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/steps\/{stepmessages.step}",
			"type": "steps"
		},
		"stepmessages.fromParticipantType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/participanttypes\/{stepmessages.fromParticipantType}",
			"type": "participanttypes"
		},
		"stepmessages.toParticipantType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/participanttypes\/{stepmessages.toParticipantType}",
			"type": "participanttypes"
		},
		"documenttemplates.actionType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/actiontypes\/{documenttemplates.actionType}",
			"type": "actiontypes"
		},
		"documenttemplates.createdBy": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/participants\/{documenttemplates.createdBy}",
			"type": "participants"
		},
		"documenttemplates.actionTypeFolder": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/folders\/{documenttemplates.actionTypeFolder}",
			"type": "folders"
		},
		"documenttemplates.modifiedBy": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/participants\/{documenttemplates.modifiedBy}",
			"type": "participants"
		},
		"stepparticipanttypes.actionType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/actiontypes\/{stepparticipanttypes.actionType}",
			"type": "actiontypes"
		},
		"stepparticipanttypes.step": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/steps\/{stepparticipanttypes.step}",
			"type": "steps"
		},
		"stepparticipanttypes.participantType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/participanttypes\/{stepparticipanttypes.participantType}",
			"type": "participanttypes"
		},
		"stepdatafields.actionType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/actiontypes\/{stepdatafields.actionType}",
			"type": "actiontypes"
		},
		"stepdatafields.step": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/steps\/{stepdatafields.step}",
			"type": "steps"
		},
		"stepdatafields.dataCollection": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/datacollections\/{stepdatafields.dataCollection}",
			"type": "datacollections"
		},
		"stepdatafields.dataField": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/datacollectionfields\/{stepdatafields.dataField}",
			"type": "datacollectionfields"
		},
		"steprelatedactiontypes.actionType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/actiontypes\/{steprelatedactiontypes.actionType}",
			"type": "actiontypes"
		},
		"steprelatedactiontypes.relatedActionType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/actiontypes\/{steprelatedactiontypes.relatedActionType}",
			"type": "actiontypes"
		},
		"steprelatedactiontypes.step": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/steps\/{steprelatedactiontypes.step}",
			"type": "steps"
		}
	},
	"actioncreate": {
		"id": "42",
		"links": {
			"step": "42--0",
			"stepTasks": [688, 689],
			"stepMessages": ["42--0--1", "42--0--2"],
			"documentTemplates": ["713"],
			"stepParticipantTypes": ["231", "232","233"],
			"otherParticipantTypes": [19],
			"stepDataFields": ["119", "117","118"],
			"stepRelatedActionTypes": [9]
		}
	},
	"linked": {
		"steps": [{
			"id": "42--0",
			"stepNumber": "0",
			"stepName": "Start",
			"description": "Nothing has happened yet",
			"actionStatus": "Active",
			"assignToMandatory": "F",
			"links": {
				"actionType": "42",
				"assignToParticipantType": null
			}
		}],
		"steptasks": [{
			"id": 688,
			"task_name": "Test optional task",
			"priority": "Normal",
			"dueDateText": "Due 7 weekdays after step change date",
			"isMandatory": "F",
			"links": {
				"actionType": "42",
				"assignToParticipantType": "19",
				"step": "42--0"
			}
		},
		{
			"id": 689,
			"task_name": "Test mandatory task",
			"priority": "Normal",
			"dueDateText": "Due 7 weekdays after step change date",
			"isMandatory": "T",
			"links": {
				"actionType": "42",
				"assignToParticipantType": "177",
				"step": "42--0"
			}
		}],
		"stepmessages": [{
			"id": "42--0--1",
			"method": "E-Mail",
			"subject": "test optional email subject",
			"message": "Some message text",
			"messageHtml": "<p>Some message text<\/p>",
			"isMandatory": "F",
			"links": {
				"actionType": "42",
				"step": "42--0",
				"fromParticipantType": "177",
				"toParticipantType": "19"
			}
		},
		{
			"id": "42--0--2",
			"method": "E-Mail",
			"subject": "Test mandatory email",
			"message": "asdas",
			"messageHtml": "<p>sasdas<\/p>",
			"isMandatory": "F",
			"links": {
				"actionType": "42",
				"step": "42--0",
				"fromParticipantType": "177",
				"toParticipantType": "19"
			}
		}],
		"documenttemplates": [{
			"id": 713,
			"name": "Sample File",
			"description": null,
			"fileName": "Some_File_Name.docx",
			"directory": "\/templates\/",
			"fileSize": 12175,
			"createdTimestamp": "2015-12-23T07:14:28+13:00",
			"modifiedTimestamp": "2015-12-23T07:14:28+13:00",
			"oldNfsPath": null,
			"documentIdentifier": "",
			"currentVersion": "",
			"installedVersion": "",
			"lastCheckinTimestamp": "",
			"generatedCount": "",
			"links": {
				"actionType": "42",
				"createdBy": "1",
				"actionTypeFolder": null,
				"modifiedBy": "1"
			}
		}],
		"stepparticipanttypes": [{
			"id": "231",
			"isRequired": "F",
			"displayOrder": 0,
			"links": {
				"actionType": "42",
				"step": "42--0",
				"participantType": "203"
			}
		},
		{
			"id": "232",
			"isRequired": "F",
			"displayOrder": 1,
			"links": {
				"actionType": "42",
				"step": "42--0",
				"participantType": "177"
			}
		},
		{
			"id": "233",
			"isRequired": "F",
			"displayOrder": 2,
			"links": {
				"actionType": "42",
				"step": "42--0",
				"participantType": "106"
			}
		}],
		"participanttypes": [{
			"id": 19,
			"name": "Client",
			"description": "Client organisation",
			"isBaseParticipantType": "F",
			"companyFlag": "F",
			"taxNumberAlias": null
		}],
		"stepdatafields": [{
			"id": 117,
			"groupLabel": "TestData",
			"fieldLabel": "Date field",
			"fieldDescription": "Date field description",
			"defaultValue": null,
			"forceDefaultValue": "F",
			"displayOrder": 0,
			"isRequired": "T",
			"links": {
				"actionType": "42",
				"step": "42--0",
				"dataCollection": "data_collection_id",
				"dataField": "270--DateField"
			}
		},
		{
			"id": 118,
			"groupLabel": "TestData",
			"fieldLabel": "Required Text Field",
			"fieldDescription": "RequiredTextField desc",
			"defaultValue": null,
			"forceDefaultValue": "F",
			"displayOrder": 0,
			"isRequired": "T",
			"links": {
				"actionType": "42",
				"step": "42--0",
				"dataCollection": "data_collection_id",
				"dataField": "270--RequiredTextField"
			}
		},
		{
			"id": 119,
			"groupLabel": "Custom Group Name",
			"fieldLabel": "Custom Field Label",
			"fieldDescription": "Custom Field Description",
			"defaultValue": null,
			"forceDefaultValue": "F",
			"displayOrder": 0,
			"isRequired": "F",
			"links": {
				"actionType": "42",
				"step": "42--0",
				"dataCollection": "data_collection_id",
				"dataField": "270--TextField"
			}
		}],
		"steprelatedactiontypes": [{
			"id": "9",
			"isMandatory": "T",
			"links": {
				"actionType": "42",
				"relatedActionType": "14",
				"step": "42--0"
			}
		}]
	},
	"meta": {
		"paging": {
			"actioncreate": {
				"recordCount": 1,
				"pageCount": 1,
				"page": 1,
				"pageSize": 50,
				"prevPage": null,
				"nextPage": null
			}
		}
	}
}
Create Action - Complex POST
POST /api/rest/actioncreate
{
"actioncreate" : {
    "actionName": "Example Action created via API",
    "fileReference": "file reference",
    "priority": "9",
    "assignedToParticipant": "1",
    "status" : "Active",
    "timestamp" : "2015-12-22",
    "stepDataField119": "First value",
    "stepDataField117": "2015-06-19",
    "stepDataField118": "Second value",
    "fileNote" : "Some file-note text",
    "links" : {
        "actionType" : "42",
        "stepTasks": [688,689],
        "documentTemplates": [713],
        "stepMessages": [1,2],
        "relatedActionType14": [3246],
        "participantType203": [1015],
        "participantType177": [1267],
        "participantType106": [978],
        "participantType19": [112]
    }
}}
 
RESPONSE:
{
	"links": {
		"actioncreate.assignedTo": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/participants\/{actioncreate.assignedTo}",
			"type": "participants"
		},
		"actioncreate.division": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/divisions\/{actioncreate.division}",
			"type": "divisions"
		},
		"actioncreate.actionType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/actiontypes\/{actioncreate.actionType}",
			"type": "actiontypes"
		},
		"actioncreate.primaryParticipants": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/participants\/{actioncreate.primaryParticipants}",
			"type": "participants"
		}
	},
	"actioncreate": {
		"id": 3304,
		"name": "Example Action created via API",
		"reference": "file reference",
		"priority": 9,
		"status": "Active",
		"statusTimestamp": "2015-12-29T07:29:05+13:00",
		"isBillableOverride": null,
		"createdTimestamp": "2015-12-29",
		"modifiedTimestamp": "2015-12-29T07:29:05+13:00",
		"isDeleted": "F",
		"deletedBy": null,
		"deletedTimestamp": null,
		"isFavorite": "F",
		"links": {
			"assignedTo": "1",
			"division": "1",
			"actionType": "42",
			"primaryParticipants": ["112"]
		}
	}
}
 
Create Action - Simple GET
GET /api/rest/actioncreate/122
{
	"links": {
		"actioncreate.step": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/steps\/{actioncreate.step}",
			"type": "steps"
		},
		"actioncreate.stepTasks": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/steptasks\/{actioncreate.stepTasks}",
			"type": "steptasks"
		},
		"actioncreate.stepMessages": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/stepmessages\/{actioncreate.stepMessages}",
			"type": "stepmessages"
		},
		"actioncreate.documentTemplates": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/documenttemplates\/{actioncreate.documentTemplates}",
			"type": "documenttemplates"
		},
		"actioncreate.stepParticipantTypes": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/stepparticipanttypes\/{actioncreate.stepParticipantTypes}",
			"type": "stepparticipanttypes"
		},
		"actioncreate.otherParticipantTypes": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/participanttypes\/{actioncreate.otherParticipantTypes}",
			"type": "participanttypes"
		},
		"actioncreate.stepDataFields": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/stepdatafields\/{actioncreate.stepDataFields}",
			"type": "stepdatafields"
		},
		"actioncreate.stepRelatedActionTypes": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/steprelatedactiontypes\/{actioncreate.stepRelatedActionTypes}",
			"type": "steprelatedactiontypes"
		},
		"steps.actionType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/actiontypes\/{steps.actionType}",
			"type": "actiontypes"
		},
		"steps.assignToParticipantType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/participanttypes\/{steps.assignToParticipantType}",
			"type": "participanttypes"
		}
	},
	"actioncreate": {
		"id": "122",
		"links": {
			"step": "122--0",
			"stepTasks": [],
			"stepMessages": [],
			"documentTemplates": [],
			"stepParticipantTypes": [],
			"otherParticipantTypes": [],
			"stepDataFields": [],
			"stepRelatedActionTypes": []
		}
	},
	"linked": {
		"steps": [{
			"id": "122--0",
			"stepNumber": "0",
			"stepName": "Start",
			"description": "Nothing has happened yet",
			"actionStatus": "Active",
			"assignToMandatory": "F",
			"links": {
				"actionType": "122",
				"assignToParticipantType": null
			}
		}]
	},
	"meta": {
		"paging": {
			"actioncreate": {
				"recordCount": 1,
				"pageCount": 1,
				"page": 1,
				"pageSize": 50,
				"prevPage": null,
				"nextPage": null
			}
		}
	}
}
Create Action - Simple POST
POST /api/rest/actioncreate
{
"actioncreate" : {
    "actionName": "A very simple request",
    "links" : {
        "actionType" : "122"
    }
}}
 
RESPONSE:
{
	"links": {
		"actioncreate.assignedTo": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/participants\/{actioncreate.assignedTo}",
			"type": "participants"
		},
		"actioncreate.division": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/divisions\/{actioncreate.division}",
			"type": "divisions"
		},
		"actioncreate.actionType": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/actiontypes\/{actioncreate.actionType}",
			"type": "actiontypes"
		},
		"actioncreate.primaryParticipants": {
			"href": "https:\/\/some-server.actionstep.com\/api\/rest\/participants\/{actioncreate.primaryParticipants}",
			"type": "participants"
		}
	},
	"actioncreate": {
		"id": 3305,
		"name": "A very simple request",
		"reference": null,
		"priority": 0,
		"status": "Active",
		"statusTimestamp": "2015-12-29T07:36:14+13:00",
		"isBillableOverride": null,
		"createdTimestamp": "2015-12-29",
		"modifiedTimestamp": "2015-12-29T07:36:15+13:00",
		"isDeleted": "F",
		"deletedBy": null,
		"deletedTimestamp": null,
		"isFavorite": "F",
		"links": {
			"assignedTo": "1",
			"division": "1",
			"actionType": "122",
			"primaryParticipants": null
		}
	}
}