Toggle menu

createCase

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 PropertiesTypeDescription
caseTypeIdStringThe 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)
userObjectDetails 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.proxyUserIdString, optionalThe 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.siteUserIdStringThe username of the user who created the case
formObjectThis object provides details that would otherwise be provided by a form submission that starts the case
form.startFormStringThe name of the form used to start the case. This form must exist
form.summaryFormString, optionalThe name of a form to display summary/read-only views of the case. Defaults to the startForm if not set
form.fieldsArray of objects, optionalThese values will be passed to the workflow as process variables
form.fields[n].nameStringThe name of the field. The form_ prefix will be added automatically (ie FIELD1 will become the process variable field_FIELD1)
form.fields[n].valueStringThe value of the field
Optional PropertiesTypeDescription
caseSubTypeIdStringThe case subtype. This must exist in the case configuration
caseStageIdStringThe case stage. This must exist in the case configuration
caseStatusStringThe 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)
caseManagerIdStringThe 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
languageStringThe language code of the case. Defaults to EN if not set
targetDateString (date-time)The target completion date for the case (the SLA) eg "2022-06-23T09:27:53Z". Must be in the future
contactObjectDetails of the person who raised the case
contact.nameStringTheir full name. Automatically mapped to form_NAME
contact.emailString (email)Their email address. Must be in a valid format. Automatically mapped to form_EMAIL
contact.phoneNumberStringTheir phone number. Automatically mapped to form_PHONENUMBER
contact.addressStringTheir address. Automatically mapped to form_ADDRESSTEXT
processVariablesObjectA process variable is created for each key-value pair. The following keys/variable names are reserved:

"assignUserName",
"_startForm",
"_summaryForm",
"initCoreVersion",
"assignUserName",
"taskList",
"appointments",
"UPLOADS",
"DELETED"
attachmentsArray of objectsEach object represents one file that will be attached to the case. The files must already exist in the filestore
attachments[n].fileStoreReferenceString, requiredThe filestore reference of the uploaded file
attachments[n].formFieldString, requiredThe 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)
closeObjectIf supplied the case will be created then closed
close.closureReasonStringThe reason for the case being closed. This must match one of the reasons set in the case configuration
close.closureNoteStringA 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"
    },
    "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

  1. "Start user {startUserId} does not exist" - If the start user supplied in the request does not exist in the environment
  2. "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
  3. "Proxy user {proxyUserId} does not exist" - If proxyUserId is supplied in the request but does not exist in then environment
  4. "Case manager {caseManagerId} does not exist" - If caseManagerId is supplied in the request but does not exist in the environment
  5. "Case type {caseTypeId} does not exist in environment" - If the caseTypeId supplied in the request does not exist in the environment
  6. "Start form {startForm} does not exist in environment" - If the startForm supplied in the request does not exist in the environment

Warning Messages

  1. "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
  2. "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
  3. "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
  4. "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
  5. "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
  6. "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
  7. "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 
  8. "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
  9. "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
Last modified on 22 September 2022

Share this page

Facebook icon Twitter icon email icon

Print

print icon