Beschrijving koppeling naar AlleyOop

Om de informatie algemeen beschikbaar te maken beschrijven we voor partners hoe Caseware de koppeling naar AlleyOop (Workflow) heeft gemaakt. Onderstaand is ontwikkeld op basis van de beschikbare SDK van AlleyOop (Pdf Download)

Opbouw aanmaak httpRequest

string authInfo = oParameters.UserName + ":" + oParameters.PassWord;
authInfo = Convert.ToBase64String(Encoding.Default.GetBytes(authInfo));

// create _httpRequest parameters
httpRequest = (HttpWebRequest)WebRequest.Create(oParameters.Url);
httpRequest.Headers["Authorization"] = "Basic " + authInfo;

http response codes

Zie pdf (Pdf Download)

Uitlezen processinstances/processdefinities

Het uitlezen van processdefinities wordt gebruikt om te bepalen voor welke workflow een workflow instance dient te worden aangemaakt voor een bepaald clientId. Een process instance bevat meerdere taken; ieder taak heeft een uniek taskId (zie ook de "tasks - GET.json").

Een clientId is een string value, gegenereerd door AlleyOop, die verder wordt geïdentificeerd door KVK-nummer, klantnummer etc.
Opmerking: Het clientId kan bijvoorbeeld het KVK-nummer zijn wat wordt vastgelegd in het Caseware dossier. Het uitlezen van de definities vindt plaats via onderstaand request:

httpRequest.Method = “GET”;
httpRequest.ContentType = "application/json";
httpRequest.Headers["X-action"] = "process-definitions";
httpRequest.Headers["X-apiKey"] = oParameters._APIkey; 

Voor de JSON response zie “process-definities GET.json”

Uitlezen Clientinformatie uit AlleyOop

In AlleyOop bevindt zich ook clientinformatie, die wordt aangemaakt vanuit een applicatie (CRM. Caseware etc.). Deze clientinformatie kan worden opgevraag aan de hand van onderstaand request:

httpRequest.Method = “GET”;httpRequest.ContentType = "application/json";
httpRequest.Headers["X-action"] = "clients";
httpRequest.Headers["X-apiKey"] = oParameters._APIkey; 

BuiltHeader("X-clientId", clients.clientId, ref httpRequest);
BuiltHeader("X-bsn", clients.bsn, ref httpRequest);
BuiltHeader("X-kvk", clients.kvk, ref httpRequest);
BuiltHeader("X-name", clients.name, ref httpRequest);
BuiltHeader("X-referId", clients.referid, ref httpRequest);
BuiltHeader("X-rsin", clients.rsin, ref httpRequest);
BuiltHeader("X-vat", clients.vat, ref httpRequest);
BuiltHeader("X-wage", clients.wage, ref httpRequest);

Uitlezen Clientinformatie uit AlleyOop

In AlleyOop bevindt zich ook clientinformatie, die wordt aangemaakt vanuit een applicatie (CRM. Caseware etc.). Deze clientinformatie kan worden opgevraag aan de hand van onderstaand request:
httpRequest.Method = “GET”;
httpRequest.ContentType = "application/json";
httpRequest.Headers["X-action"] = "clients";
httpRequest.Headers["X-apiKey"] = oParameters._APIkey;

BuiltHeader("X-clientId", clients.clientId, ref httpRequest);
BuiltHeader("X-bsn", clients.bsn, ref httpRequest);
BuiltHeader("X-kvk", clients.kvk, ref httpRequest);
BuiltHeader("X-name", clients.name, ref httpRequest);
BuiltHeader("X-referId", clients.referid, ref httpRequest);
BuiltHeader("X-rsin", clients.rsin, ref httpRequest);
BuiltHeader("X-vat", clients.vat, ref httpRequest);
BuiltHeader("X-wage", clients.wage, ref httpRequest);

Voor resultaat van het request zie “clients – GET.json”

Aanmaken van een workflow

httpRequest.Method = “POST”;httpRequest.ContentType = "application/json";
httpRequest.Headers["X-action"] = "process-instances";httpRequest.Headers["X-apiKey"] = oParameters.ApIkey;
httpRequest.Headers["X-clientId"] = processInstance.ClientId;httpRequest.Headers["X-processKey"] = processInstance.ProcessKey;
httpRequest.Headers["X-periodStart"] = processInstance.PeriodStart;httpRequest.Headers["X-periodEnd"] = processInstance.PeriodEnd;

Bij het versturen van de informatie, dient het clientId bekend te zijn.
Voor de JSON response zie “process-instance GET.json”

Controleren bestaanbaarheid workflowinstance

httpRequest.Method = “GET”;
httpRequest.ContentType = "application/json";
httpRequest.Headers["X-action"] = "process-instances";
httpRequest.Headers["X-apiKey"] = oParameters.ApIkey;

// optional headers
builtHeader("X-taskId", processInstance.TaskId, ref httpRequest);
builtHeader("X-clientId", processInstance.ClientId, ref httpRequest);
builtHeader("X-periodStart", processInstance.PeriodStart, ref httpRequest);
builtHeader("X-periodEnd", processInstance.PeriodEnd, ref httpRequest);
builtHeader("X-processKey", processInstance.ProcessKey, ref httpRequest);

Verplichte headers zijn X-action en X-apiKey. Indien verder geen headers worden meegegeven, worden alle instances geretourneerd.
Voor de JSON response zie “process-instance GET.json”
Van deze JSON worden op dit moment slechts onderstaande elementen gebruikt:
clientId, processKey, processName, processVersion, instanceID, periodStart, periodEnd

Verwijderen van bestaande Workflowinstance

httpRequest.Method = “DELETE”;httpRequest.ContentType = "application/json";
httpRequest.Headers["X-action"] = "process-instances";
httpRequest.Headers["X-apiKey"] = oParameters.ApIkey;
httpRequest.Headers["X-instanceId"] = processId;httpRequest.Headers["X-reason"] = "removed during process";

Response levert een lege json.
Zie verder ook http response codes.

Versturen van een signaal

httpRequest.Method = “PUT”;
httpRequest.ContentType = "application/json";
httpRequest.Headers["X-action"] = "tasks";
httpRequest.Headers["X-apiKey"] = oParameters.ApIkey;

// necessary headers
builtHeader("X-clientId", task.ClientId, ref httpRequest);
builtHeader("X-periodStart", task.PeriodStart, ref httpRequest);
builtHeader("X-periodEnd", task.PeriodEnd, ref httpRequest);
builtHeader("X-processkey", task.Processkey, ref httpRequest);
builtHeader("X-signal", task.Signal, ref httpRequest);

Een lege JSON wordt geretourneerd.
Zie verder HTTP-reponse codes
Signalen dienen opeenvolgend te zijn in de workflow
Indien een signaal niet voldoet/aan de beurt is, wordt de http response code: 404 = no given task

Verzameling actieve taken (voor een workflow instance)

httpRequest.Method = “GET”;
httpRequest.ContentType = "application/json";
httpRequest.Headers["X-action"] = "tasks";
httpRequest.Headers["X-apiKey"] = oParameters.ApIkey;
builtHeader("X-clientId", task.ClientId, ref httpRequest);
builtHeader("X-group", task.Group, ref httpRequest);
builtHeader("X-periodStart", task.PeriodStart, ref httpRequest);
builtHeader("X-periodEnd", task.PeriodEnd, ref httpRequest);
builtHeader("X-processKey", task.Processkey, ref httpRequest);
builtHeader("X-signal", task.Signal, ref httpRequest);

Het ophalen van taken kan volgens bovenstaande headers voor 1 taak of voor alle taken van een taskId

Voor de JSON response zie “tasks - GET.json”

De tasks-service met methode (X-action) "Tasks" is het beheren en het opvragen van actieve taken

De "task-history" service betreft de reeds afgeronde taken voor een process-instance (wordt gebruikt om op dossierniveau de afgeronde taken te kunnen presenteren in een formulier).
Zowel Ophalen van actieve als historische taken worden gebruikt en zijn noodzakelijk.

De parameters zijn vernoemd in "https://alley-oop.zendesk.com/hc/nl/articles/203040171-Task-history"

httpRequest.Method = “POST”;
string boundary = "------------------------" + DateTime.Now.Ticks;

// built headers in a list
List<HttpRequestHeaders> headerList = new List<HttpRequestHeaders>();
headerList.Add(new HttpRequestHeaders {HeaderKey="X-action",HeaderValue="files"});
headerList.Add(new HttpRequestHeaders {HeaderKey="X-apiKey",HeaderValue=oParameters.ApIkey };
headerList.Add(new HttpRequestHeaders {HeaderKey="X-instanceId",HeaderValue = oParameters.InstanceId });
headerList.Add(new HttpRequestHeaders { HeaderKey = "X-type", HeaderValue = oParameters.FileType });

// define all headers
httpRequest.ContentType = "multipart/form-data; boundary=" + boundary;
httpRequest.Headers["X-action"] = "files";
httpRequest.Headers["X-apiKey"] = oParameters.ApIkey;
httpRequest.Headers["X-instanceId"] = task.TaskId;
httpRequest.Headers["X-type"] = oParameters.fileType;

byte[] boundaryBytes = Encoding.ASCII.GetBytes(newLine + "--" + boundary + newLine);
string fileformat = "Content-Disposition: form-data; name=\"file\""+";filename=\"{0}\""+newLine+"Content-Type: "+ "\"{1}\"" + newLine + newLine;
string fileheader = string.Format(fileformat, Path.GetFileName(fullFileName), httpRequest.ContentType);

using (var reqStream = httpRequest.GetRequestStream())
{
// add again header information to reqStream (regars headers, defined in the headerlist)
foreach (HttpRequestHeaders header in headerList)
{
string headerkey = header.HeaderKey;
string headervalue = header.HeaderValue;
string format = "Content-Disposition: form-data; name=\"{0}\"" + newLine + newLine + "{1}";
var value = string.Format(format, headerkey, headervalue);
byte[] headerByte = Encoding.UTF8.GetBytes(value);
// write boundary and headerinfo
reqStream.Write(boundaryBytes, 0, boundaryBytes.Length);
reqStream.Write(headerByte, 0, headerByte.Length);

}
// write fileinformation
// write boundary (bytes)
reqStream.Write(boundaryBytes, 0, boundaryBytes.Length);

// create header for file
byte[] fileheaderBytes = Encoding.UTF8.GetBytes(fileheader);

reqStream.Write(fileheaderBytes, 0, fileheaderBytes.Length);
// finally, write file by creating filestream, reading filestream and write stream to http
byte[] buffer = new byte[8192];
FileStream fileStream = new FileStream(fullFileName, FileMode.Open, FileAccess.Read);
var bytesread = fileStream.Read(buffer, 0, buffer.Length);
while (bytesread > 0)
{
reqStream.Write(buffer, 0, bytesread);
bytesread = fileStream.Read(buffer, 0, buffer.Length);
}

fileStream.Close();
// at last, add a trailer to the upload
byte[] trailer = Encoding.ASCII.GetBytes(newLine + "--" + boundary + "--" + newLine);
reqStream.Write(trailer, 0, trailer.Length);
reqStream.Close();
}

Type is geheel zelf te definiëren.

Voor de json die wordt geretourneerd zie “files – POST.json”

clients - Get.json

[{
"clientId": "040d1bb2-b0a9-45cc-b605-b170d2f3150f",
"name": "SRA CCM 2016",
"referId": "",
"rsin": "",
"bsn": "",
"vat": "",
"wage": "",
"kvk": "12345678",
"inactive": false
}]

process-definitions GET.json

[{
"key": "CONTROLE_08",
"name": "Controle",
"description": "Controle",
"version": 1
}]

process-instance GET.json

[{
"clientId": "49142e51-fcd5-4368-a085-16601831541e",
"processKey": "SAMENSTELLEN_09",
"processName": "Samenstellen 0.9",
"processVersion": 2,
"instanceId": "1332501",
"processDescription": "Samenstellen",
"periodStart": "2017-01-01",
"periodEnd": "2017-12-31"
}]

tasks - GET.json

[{
"taskId": "1365055",
"processInstanceId": "1365031",
"clientId": "105a2935-ba55-4e2c-b6b7-05f9b46f0327",
"periodStart": "2017-01-01",
"periodEnd": "2017-12-31",
"key": "informatie_compleet",
"name": "Informatie compleet",
"startDate": "2018-06-18",
"dueDate": "2018-06-18"
},
{
"taskId": "1365044",
"processInstanceId": "1365031",
"clientId": "105a2935-ba55-4e2c-b6b7-05f9b46f0327",
"periodStart": "2017-01-01",
"periodEnd": "2017-12-31",
"key": "voorbereiding",
"name": "Voorbereiding",
"startDate": "2018-06-18",
"dueDate": "2018-06-18"
}]

files - Post.json

{
"uploadId": "448F6E4CEFABDFC1C12582B00034A76C",
"typeLabel": "Concept jaarrekening",
"typeId": "CONCEPT_JAARREKENING",
"clientId": "105a2935-ba55-4e2c-b6b7-05f9b46f0327",
"clientName": "Workflow BV",
"apiName": "CASEWARE USER/ALLEYOOP",
"processId": "1365031",
"attachments": ["Bevestiging bij de jaarrekening 2016.pdf"],
"attachmentsInfo": [{
"filename": "Bevestiging bij de jaarrekening 2016.pdf",
"filesize": 56059,
"filesizeinfo": "55kb",
"filetime": "2018-06-18 11:35:07"
}]
}