Status Change and balance payment via API
Each form case (GET/ instances/{id}) can have multiple tasks (GET/instances/{id}/tasks). These tasks
are generated by the system as the form case progresses, there may also be multiple simultaneous tasks within
a case - although currently not in Fastighetsägarna Documents. Work tasks appears in users inboxes and
represents the work that can be performed within a case.
In connection to starting a form case, information is returned concerning the new form case in the following format:
{ "success":true, "Items": [ { "success":true, "ObjectClass":"process.instance", "Name":"Hyreskontrakt för lokal", "Id":"3e1871cc-e43c-4bcf-8724-1dcb04a99318", "ReferenceId":"3e1871cc-e43c-4bcf-8724-1dcb04a99318", "resourceURI":"/tasks/4673ff92-69e3-49c9-ae4f-224b0f14edfe"} ] } |
In this Json object you will find the form case ID but also the first work task URI (resourceURI).
If the work task is opened through the API call GET /tasks/{taskid} then the information is returned in the following format (more fields are returned than in this example):
{ "Id":"4673ff92-69e3-49c9-ae4f-224b0f14edfe", "ReferenceId":"TaskCreate", "Name":"Utkast", "Status":"Ready", "CreatedDate":"2011-07-13T21:43:04Z", "CompletedDate":null, "CompletedBy":null, "CompletedByUserId":null, "InstanceName":"12B.2 Hyreskontrakt för lokal", "InstanceId":"3e1871cc-e43c-4bcf-8724-1dcb04a99318", "PerformPermission":true } |
Despite task ID and its name there is a ReferenceId in the example above "TaskCreate". Reference ID: for tasks are identifiers that will not be changed and thus can be programmed towards predictability. In the future, there may be more work tasks but existing ones will be supported forthwith. By inspecting a tasks ReferenceID- proprty you can see what type of task it is.
In order to complete a task and thereby change the case state you first need to find out what actions are available by using the API-call GET /tasks/{id}/actions
Just like with ReferenceId for tasks, actions also have ReferenceId:s to program against.
The following tasks and actions (with ReferenceId:s) are available in the workflow for the chosen form case process.
TaskCreate | Work with draft (all info can be edited) |
*ActionPay | Change the status of the form case to sharp, if you are not a license customer you change the state to "TaskPay", otherwise "TaskPaid" |
TaskPay | Payment task to confirm order and go through with payment |
*ActionComplete | Confirms the order and performs balance payment, where after state is changed to "TaskPaid". If for example the balance is too low, this is returned in connection to POST /tasks/{id}/action/actioncomplete in TaskPay. The error message is then available in the property "message" in the status object. |
*ActionCancel | Cancels the payment and changes status to "TaskCreate" or "TaskPaid" depending on which status the case had earlier. |
TaskPaid | Work with sharp case (Draft watermark removed for payed forms. All info except the field Kontrakt.KontraktNr can be edited). |
*ActionComplete | Completes and archives the form case. Possibility to edit ceases. |
*ActionPay | Changes status of the case to TaskPay again unless license customer and let user pay for forms added since last payment. |
The process is that a case is status changed from TaskCreate -> TaskPay -> TaskPaid and thereafter may be completed.
If you want to fetch the order for a payment task (currently only TaskPay) you can use the API-call GET /tasks/{id}/order
You can complete a task by performing a HTTP POST to one of these actions, check out the following API-calls:
POST /tasks{id}/actions/actionpay |
Change status to TaskPay from TaskCreate |
POST /tasks{id}/actions/actioncomplete |
Change status to TaskPaid from TaskPay |
Note that the task you complete must have status "Ready" meaning it can't already have been completed. Each time you post to an action in the format above you get a status object returned which indicates success or failure via the success-property and in some cases display a message in the property message. Also, a new TaskId is often returned (depends on where you are in the process), this TaskId represents the task where you changed the status.
GET /domains/current represent the logged in users company/organization. All users belonging to the same domain automatically get access to all form cases within the company/organisation and uses the same balance for payments.
If you want access to the logged in users company balance and transaction history, this is available through the following API-calls:
GET /domains/current/balance
GET /domains/current/transactions
If you wish to test balance payment you need a test balance. Send an email to fastighetsagarna.dokument@barium.se to receive this.