system controllers allow complete control over inbound integrations system controllers allow you to script any logic, and return any type of data back to the caller it can either be api call from an external system or from servicely’s client side scripting with the scripting, you have access to perform table operations (refer to table api (server) ) on any table your api authenticated session allows (refer to authentication (inbound)) or your current user session if the controller is called as part of a client side operation you can also call script library functions as required url format to access a controller, the url endpoint is https //\<instancename> servicely ai/controller/\<controllername> example if the instance name is testinstance and the controller name is updateincidenttst, the url will be https //testinstance servicely ai/controller/updateincidenttst authentication possible authentication methods, refer authentication (inbound) for more information basic username & password bearer token hmac header validation hmac body validation accessing inbound payload’s attributes for the following sample payload { "id" "b4321", "name" "bob the builder", "phone" "0404111222", "relateddata" { "managerid" "a1234" } } you can either access the attribute directly in your controller script, e g log info("name sent was " + name); // should output "bob the builder" or you can access the entire payload with the data variable log info("payload sent was " + json stringify( data, null, 2)); // should output the whole stringified json payload customising the response format in version 1 10 63, the ability to customize the response format of a system controller was introduced the addition to the api allows you to customize the message format, the content type, http status, and add headers to the systemcontroller response controller object the ‘ controller ’ object allows customisation of the message header if the ‘ setbody ’ or ‘ setjsonbody ’ methods are called, these override the v1 functionality of using the ‘ answer ’ variable the available methods are listed below function returns description setbody(body string) reference to controller object sets the body of the response to the explicit string provided the body will not be modified or interpreted in any way setjsonbody(obj any?) reference to controller object sets the response as a json object the passed object will be serialised to a json object directly (will not be contained under the ‘ data’ property of the v1 api) setcontenttype(contenttype string) reference to controller object sets the http ‘content type’ header to the requested mime type setstatus(code number) reference to controller object sets the http status code for the request setheader(name string, value string) reference to controller object sets the specified http header to the requested value examples the examples below are split into the source that is calling the controllers based on the typical use cases there is no difference in syntax and requirements of parameters that can be passed into the controller as well as its return values example api from external systems below is an example of an api payload sent to a servicely environment that replies with a greeting the servicely screenshot below shows how such controller can be configured ➜ https v sandbox servicely ai/controller/greetingexamplecontroller name=bob post /controller/greetingexamplecontroller http/1 1 { "name" "bob" } http/1 1 200 ok content length 28 content type application/json { "data" "hello bob!" } example for client side script’s request below is an example of a controller script that is intended to get a user record’s location id and name for the purpose of a client side scripting (such as ui event docid 6qw7md16ndkqk0yx6bus5 ) assumptions client side scripting will pass a parameter called “userid” client side scripting will handle the returned payload that has two attributes of “locationid” and “locationname” answer = {}; // query the user table for the record with the provided userid parameter if (userid) { let userrec = table("user", userid); if (userrec) { if (userrec location hasvalue()) { answer locationid = userrec location value(); answer locationname = userrec location displayvalue(); } } } answer; example version 2 api to provide a custom json format (no ‘data’ element) controller setjsonbody({hello "world!!!!"}); …will result in the complete message… { "hello" "world!!!!"} example version 2 api to provide a custom xml response controller setcontenttype("application/xml");controller setbody("\<xml>\<number>inc0000001\</number>\</xml>"); …wil produce content type application/xml \<xml> \<number>inc0000001\</number>\</xml> example script to create an incident with classification and error handling example of a controller script to create an incident ticket from an external source with a level of classification mapping and a level of error handling / sample incoming payload { "issuesummary" "unresponsive db", "classification" "db access" } sample return payload { "data" { "status" "200", "message" "inc0001234 created ", "servicelyid" "b1d4dc612b4c11ee857dea22dfa25102" } } / let answerpayload = {}; if (issuesummary) { // check if summary was provided in the inbound api payload // 1 map ticketclassification let ticketclassification = "1234"; // default classification id switch(classification) { case "db access" ticketclassification = "5678"; break; case "server performance" ticketclassification = "a6d5"; break; default break; } // 2 create incident try { let newinc = table("incident") newrecord() requestor(user getid()) // example, if we are defaulting requestor to current user used by the integration's authentication shortdescription(issuesummary) classification(ticketclassification) create(); answerpayload status = "200"; answerpayload message = newinc number() + " created "; answerpayload servicelyid = newinc getid(); // unique servicely db id for the newly created incident record } catch ( e) { log error("exception with controller testincidentcreate exception message " + e); answerpayload status = "500"; answerpayload message = "exception with controller testincidentcreate exception message " + e; } } else { answerpayload status = "500"; answerpayload message = "issue summary not provided "; } answer = answerpayload; // set the return payload