Creates a new case of the supplied type. The case can also be set to be closed immediately after it is created.
Any files that need to be attached to the case must already exist in the platform's file store, it is not possible to supply files with the call to create the case.
Before creating a case, the relevant case type must already exist and parameters supplied in your call should match the case configuration.
Cases must be set as started by a valid user.
Namespace
goss.CaseManagement.v1.api.createCase
Worker
serverlibrary
Parameters
| Required Properties | Type | Description |
|---|---|---|
| caseTypeId | String | The case type ID for the type of case to be created (this is generally the case name in lower case and is set as part of your case configuration) |
| user | Object | Details of the user starting the case. This user will be recorded as the case owner (ie as if they had submitted the form to start the case). Usernames are the account usernames of the relevant website users, which will likely be GUIDs |
| user.proxyUserId | String, optional | The username of a user who created this case on behalf of the siteUserId (ie as if they had used the Assisted Service template). Defaults to null if not set |
| user.siteUserId | String | The username of the user who created the case |
| form | Object | This object provides details that would otherwise be provided by a form submission that starts the case |
| form.startForm | String | The name of the form used to start the case. This form must exist |
| form.summaryForm | String, optional | The name of a form to display summary/read-only views of the case. Defaults to the startForm if not set |
| form.fields | Array of objects, optional | These values will be passed to the workflow as process variables |
| form.fields[n].name | String | The name of the field. The form_ prefix will be added automatically (ie FIELD1 will become the process variable field_FIELD1) |
| form.fields[n].value | String | The value of the field |
| Optional Properties | Type | Description |
| caseCardTitle | String | Used in the subject of the history written by the case, and will appear as the title of the corresponding card on the User Requests template. If not set the default text "Case Management v1" will be used |
| caseSubTypeId | String | The case subtype. This must exist in the case configuration |
| caseStageId | String | The case stage. This must exist in the case configuration |
| caseStatus | String | The case status. This must exist in the case configuration. Only open, in progress and escalated statuses can be set (creating closed cases is described below) |
| caseManagerId | String | The username of the case manager (ie the account username, which may be a GUID) the case should be assigned to. The case manager must be a member of the relevant case manager group in the case configuration. If not provided, or invalid, the case won't be assigned and will be claimable by anyone in the configured case manager group |
| language | String | The language code of the case. Defaults to EN if not set |
| targetDate | String (date-time) | The target completion date for the case (the SLA) eg "2022-06-23T09:27:53Z". Must be in the future |
| contact | Object | Details of the person who raised the case |
| contact.name | String | Their full name. Automatically mapped to form_NAME |
| contact.email | String (email) | Their email address. Must be in a valid format. Automatically mapped to form_EMAIL |
| contact.phoneNumber | String | Their phone number. Automatically mapped to form_PHONENUMBER |
| contact.address | String | Their address. Automatically mapped to form_ADDRESSTEXT |
| processVariables | Object | A process variable is created for each key-value pair you supply. The following keys/variable names are reserved: "assignUserName", "_startForm", "_summaryForm", "initCoreVersion", "taskList", "appointments", "UPLOADS", "DELETED" These are also reserved: "form_CASETYPE", "form_CASETYPENAME", "form_CASETYPEDESC", "form_CASESUBTYPE", "form_CASESUBTYPEDESC", "form_CASESUBTYPENAME", "form_CASETARGETDATE", "form_CASEASSIGNEE", "form_INITCASETYPE", "form_CASESTAGE", "form_CASESTAGEDESC", "form_CASESTAGENAME", "form_NAME", "form_PHONENUMBER", "form_EMAILADDRESS", "form_ONBEHALFOFNAME", "form_STATUS", "form_STATUSDESC", "form_ADDRESSTEXT", "form_AGENTROLEDESC", "form_CASETARGETDATE", "form_CASETARGETSTR", "form_CASEREMINDERDATE", "form_CLOSEDATE", "form_CASECLOSENOTES", "form_CASECLOSEREASONDESC", "form_CASECLOSEREASON", "form_LANGUAGE", "form_LABELA", "form_LABELB", "form_LABELC", "form_LABELD", "form_LABELE" |
| attachments | Array of objects | Each object represents one file that will be attached to the case. The files must already exist in the filestore |
| attachments[n].fileStoreReference | String, required | The filestore reference of the uploaded file |
| attachments[n].formField | String, required | The name of a form field the file was notionally uploaded by (needed so the file can be displayed/downloaded on future forms that engage with the case) |
| close | Object | If supplied the case will be created then closed |
| close.closureReason | String | The reason for the case being closed. This must match one of the reasons set in the case configuration |
| close.closureNote | String | A note that will be added to the case history and the close case email that gets sent to the person who raised the case |
Examples
See Case Management API for a full example call.
This first example shows the minimum that needs to be set to raise a case:
{
"caseTypeId": "testcasecreation",
"form": {
"startForm": "TESTSEARCHCASECREATION"
},
"user": {
"siteUserId": "testcasecreationowner"
}
}
This example shows the full parameter structure:
{
"caseTypeId": "mynewcase",
"user": {
"proxyUserId": "STAFF1",
"siteUserId": "TIMG"
},
"form": {
"startForm": "MYNEWCASE",
"fields": [{
"field": "TESTFIELD1",
"value": "Value 1"
}, {
"field": "TESTFIELD2",
"value": "Value 2"
}],
"summaryForm": "MYSUMMARYFORM"
},
"caseSubTypeId": "GeneralEnquiry",
"caseManagerId": "CASEMANAGER1",
"caseStageId": "Stage 1",
"caseStatus": "Open",
"contact": {
"phoneNumber": "01752123456",
"name": "Tim Gulliver",
"address": "24 Darklake View, Plymouth, PL67TL",
"email": "user@example.com"
},
"language": "EN",
"targetDate": "2022-06-15T14:00:29Z",
"processVariables": {
"customVar1": "CUSTOMVAR1",
"form_SERVICEREQUESTTEXT": "My new case"
},
"attachments": [{
"fileStoreReference": "73CB6FDB-2C50-4D53-823B-D0AF2A8242FC",
"formField": "UPLOAD"
}],
"close": {
"closureNote": "Closed",
"closureReason": "Passed to another organisation"
}
}
Responses
Success
{
"id": 25,
"result": {
"success": true,
"caseBusinessKey": "7551-2705-6145-8051",
"duration": "4175 ms",
"errors": [],
"warnings": [],
"case": {
"startUserId": "testcasecreationowner",
"startTime": "2022-06-15T14:32:48Z",
"businessKey": "7551-2705-6145-8051",
"endTime": null,
"id": "30915001",
"version": "1.29.0",
"caseManager": {
"userName": "",
"displayName": ""
},
"contact": {
"name": "",
"phoneNumber": "",
"address": "",
"addressParts": []
},
"initCaseType": {
"id": "testcasecreation",
"name": ""
},
"caseType": {
"id": "testcasecreation",
"name": "Test Case Creation",
"description": "Test Case Creation"
},
"status": {
"code": "New",
"description": "New"
},
"readOnlyForm": "",
"readOnlyTemplate": "TESTSEARCHCASECREATION",
"formData": {
"form_CASETARGETDATE": "",
"form_CASESUBTITLE": "",
"form_LANGUAGE": "EN",
"form_CLOSEDATE": "",
"form_CASETYPE": "testcasecreation",
"form_STARTDATE": "2022-06-15T14:32:48Z",
"form_CASETARGETHOURS": 0,
"form_INITCASESUBTYPE": "",
"form_CASETYPENAME": "Test Case Creation",
"form_CASESTAGEDESC": "",
"form_STATUS": "New",
"form_PROCESSNAME": "Case Management v1",
"form_VERSION": "v1",
"form_CASESUBTYPE": "",
"form_NUMBEROFTASKSDONE": 0,
"form_BUSINESSKEY": "7551-2705-6145-8051",
"form_CASETYPEDESC": "Test Case Creation",
"form_CASESTAGENAME": "",
"form_CASETARGETMINS": 0,
"form_STATUSDESC": "New",
"form_CASEREMINDERDATE": "",
"form_CASETARGETDAYS": 0,
"form_INITCASETYPE": "testcasecreation",
"form_CASESUBTYPEDESC": "",
"form_INITCASESTAGE": "",
"form_CASEREMINDERSTR": "",
"form_INITASSISTED": "",
"form_CASESUBTYPENAME": "",
"form_CASETARGETSTR": "",
"form_NAME": "",
"form_SERVICEREQUESTTEXT": " (Test Case Creation)",
"form_CASESTAGE": "",
"form_NUMBEROFTASKSTODO": 0,
"form_INITUSERNAME": "testcasecreationowner"
},
"citizenUserName": "testcasecreationowner",
"formNameAdditionalDetails": "",
"systemUserName": "CMSYSTEMUSER",
"citizenFullName": "testcasecreationowner",
"language": "EN",
"formSuffixCitizen": "EN",
"assignGroupFull": "",
"caseCom": {
"staffTimer": {
"days": 0,
"hours": 0,
"mins": 0
},
"citizenTimer": {
"days": 0,
"hours": 0,
"mins": 0
},
"count": 0,
"items": [],
"todo": 0,
"done": 0
},
"emailSendFrom": "gossol2-dev@gosshosted.com",
"assignGroupName": "",
"caseName": "Test Case Creation",
"proxyFullName": "",
"timerFarFuture": "2222-02-22T22:22:22.000Z",
"readyForAction": "No",
"pauseOnContactCitizen": false,
"isAssisted": false,
"proxyUserName": "",
"caseSubs": {
"count": 0,
"items": []
},
"formNameReadOnlyCitizenAlt": "",
"historyLabelA": "Case Management - Test Case Creation",
"historyLabelB": "7551-2705-6145-8051",
"historyLabelC": "notes",
"historyLabelD": "",
"timerPausedTarget": "",
"caseWorkingScheme": "working",
"groupEscalation": "",
"systemUserFull": "System User",
"assignUserFull": "",
"staffViewedCase": "No",
"groupManagerFull": "CM-TESTCASECREATIONMANAGER",
"languageStaff": "en",
"caseEscalated": "No",
"emailGroup": "No",
"timerPausedReminder": "",
"isCalendarDays": false,
"languageCitizen": "EN",
"caseDesc": "Test Case Creation",
"formSuffixStaff": "EN",
"citizenHasAccount": "Yes",
"groupManager": "CM-TESTCASECREATIONMANAGER",
"initiator": "testcasecreationowner",
"pauseCounter": 0,
"attachments": []
},
"messages": [{
"message": "getting case type",
"timestamp": "2022-06-15T14:32:47.270Z",
"data": {},
"elapsedTime": "0 ms"
}, {
"message": "Got case type",
"timestamp": "2022-06-15T14:32:47.442Z",
"data": {},
"elapsedTime": "172 ms"
}, {
"message": "Getting users",
"timestamp": "2022-06-15T14:32:47.442Z",
"data": {
"users": [{
"name": "testcasecreationowner",
"found": true,
"groups": [],
"id": "1496"
}]
},
"elapsedTime": "0 ms"
}, {
"message": "Got requested users",
"timestamp": "2022-06-15T14:32:47.463Z",
"data": {
"users": [{
"name": "testcasecreationowner",
"found": true,
"groups": [],
"id": "1496"
}]
},
"elapsedTime": "21 ms"
}, {
"message": "Checking whether testcasecreationowner can start a case",
"timestamp": "2022-06-15T14:32:47.464Z",
"data": {},
"elapsedTime": "1 ms"
}, {
"message": "Check complete",
"timestamp": "2022-06-15T14:32:47.501Z",
"data": {
"canStartResponse": {
"userIds": ["testcasecreationowner"]
}
},
"elapsedTime": "37 ms"
}, {
"message": "Starting attachments existence check",
"timestamp": "2022-06-15T14:32:47.587Z",
"data": {},
"elapsedTime": "86 ms"
}, {
"message": "validated",
"timestamp": "2022-06-15T14:32:47.587Z",
"data": {
"validated": true
},
"elapsedTime": "0 ms"
}, {
"message": "Starting case creation",
"timestamp": "2022-06-15T14:32:47.587Z",
"data": {},
"elapsedTime": "0 ms"
}, {
"message": "Workflow request",
"timestamp": "2022-06-15T14:32:47.587Z",
"data": {
"processDefinition": "casemanagementv1",
"userId": "testcasecreationowner",
"variables": {
"_startForm": "TESTSEARCHCASECREATION",
"_startFormDescription": "Test Case Creation",
"_summaryForm": "TESTSEARCHCASECREATION",
"form_CASETYPE": "testcasecreation",
"form_LANGUAGE": "EN",
"form_VERSION": "V1"
},
"fileReferences": {},
"replaceExistingFiles": false,
"historyRecording": {
"labels": {
"labela": "${PROCESSNAME}",
"labelb": "${BUSINESSKEY}"
},
"subject": {
"description": "${PROCESSDESCRIPTION}",
"userId": "TESTCASECREATIONOWNER",
"proxyUserId": null
},
"event": {
"userId": "TESTCASECREATIONOWNER",
"proxyUserId": null,
"event": "STARTWORKFLOW",
"description": "Process Started",
"userRole": "user",
"private": false
},
"storeFormData": false,
"formName": "TESTSEARCHCASECREATION",
"logSubmission": true,
"logSummary": "true"
}
},
"elapsedTime": "0 ms"
}, {
"message": "Case created",
"timestamp": "2022-06-15T14:32:50.876Z",
"data": {
"id": "30915001",
"businessKey": "7551-2705-6145-8051"
},
"elapsedTime": "3289 ms"
}, {
"message": "Get case request",
"timestamp": "2022-06-15T14:32:50.876Z",
"data": {
"case": {
"isActive": false,
"caseId": "7551-2705-6145-8051"
},
"user": {
"siteUserName": "testcasecreationowner",
"siteUserId": 1496
},
"childEntities": {
"notes": {},
"attachments": {}
},
"contextVars": {
"SITEUSERID": 1496,
"SITEUSERNAME": "testcasecreationowner",
"PROCESSBUSINESSKEY": "7551-2705-6145-8051"
}
},
"elapsedTime": "0 ms"
}],
"startTime": "2022-06-15T14:32:47.270Z",
"endTime": "2022-06-15T14:32:51.445Z"
},
"jsonrpc": "2.0"
}
Error Messages
- "Start user {startUserId} does not exist" - If the start user supplied in the request does not exist in the environment
- "Could not authorise start user {startUserID} to start a case" - If the start user supplied in the request is not a member of the Case Management Workflow initiator group
- "Proxy user {proxyUserId} does not exist" - If proxyUserId is supplied in the request but does not exist in then environment
- "Case manager {caseManagerId} does not exist" - If caseManagerId is supplied in the request but does not exist in the environment
- "Case type {caseTypeId} does not exist in environment" - If the caseTypeId supplied in the request does not exist in the environment
- "Start form {startForm} does not exist in environment" - If the startForm supplied in the request does not exist in the environment
Warning Messages
- "Could not assign case manager {caseManagerId} to case" - If caseManagerId is supplied in the request but is not a member of the Case Type's Case Manager Group
- "Summary form {summaryForm} does not exist in environment defaulting to {startForm}" - If the summaryForm supplied in the request does not exist in the environment the case will be created using the startForm as the summary form
- "Attachment {fileStoreReference} does not exist in environment and has not been able to be attached to the case" - If an attachment supplied in the requst does not exist in the file store
- "Case type {caseTypeId} does not support stage {caseStageId}, defaulted stage to blank" - If the caseStageId supplied in the request does not exist the case will be created with a blank stage
- "Case type {caseTypeId} does not support sub type {caseSubTypeId}, default sub type to blank" - If the caseSubTypeId supplied in the request does not exist in the case type the case will be created with a blank stage
- "Case type {caseTypeId} does not support status {caseStatus}, using default status" - If the caseStatus does not exist in the case type's In progress statuses
- "Case type {caseTypeId} does not support closure reason {closureReason}, defaulting to default closure reason {defaultClosureReason}" - If the closureReason supplied in the request does not exist in the environment
- "Case type {caseTypeId} requires that task {taskName} must be completed {task.min} times" - If the case type has minimum task limit rules and a close object has been provided in the request the warning will be returned for each task that minimum task rules have not been met
- "Target date {targetDate} is in the past so default case target rules have been applied" - If the targetDate supplied in the request is in the past the case will be created and the default closure target rules for the case will be applied
Share this page
