digitalstate / services

The DigitalState Services Microservice

Services

The DigitalState Services Microservice

Table of Contents

• Documentation
• References
• Contributing
• Credits

Documentation

Further documentation can be found in the Documentation Repository.

References

• Api
• Configurations
• Permissions
• Docker

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Credits

This work has been developed by DigitalState.io

services's Issues

Add API Scenario Type

Api scenario type allows the detailing of a API and link(s) to API endpoints.

Example Usage:

1. Garbage Pickup Schedule Service: Has a Widget to allow a user to look it up quickly, but there is also a public API that developers can use to connect their apps to and provide garbage look up abilities.

Add submission details on the POST submissions request

Add Life Events Entity

The Life Events Entity is similar to Services and Service Scenarios.

Life Events have a Title, Description and Presentation.

Life Events have a list of Related Services.

Unable to save scenario with type property set to `external`.

The exception thrown by the Service MS is "Type does not exist."

Posting to special scenario submissions endpoint should return the entity (ACLed) instead of an empty object

Add ability to upload files that are used by services/scenarios

Example: Upload a PDF which is used by a service scenario

fix {{services}}{{environment}}/scenarios/UUID/form/translation to use CMS

@mario-digitalstate see https://github.com/DigitalState/Cms/blob/develop/translations-howto.md and lets do a server to server setup for pulling the specific translations.

Camunda Function as a Service Endpoints

Ability to call Functions as a service that active a camunda process.

Todos:

• create FaaS in core
• POST capability
• GET capablity
• Docs
• Permissions
• Function Entity
• Camunda /start for ID and Key

---

Design Notes

1. Support POST (GET with a body is not supported by all http clients.)
2. Body should be transformed into Camunda Variables. Use same format as Camunda Variables object
3. Camunda variablesInReturn property should configure the returned API response
   1. Body
   2. Status Code
   3. headers
4. Ability to call a BPMN based on key and based on ID. This configuration should be in the Service Type configuration. You should not be able to call any process you wish. Only processes that are exposed as a FaaS.
5. BU owner of a FaaS service will be what controls the security access.

---

Use Cases

1. First use case will be the ability for Formio forms to make requests to FaaS service for server side validations. Look into whether this should be a function call that is activated by Formio or by the Service Microservice.

---

Endpoint Examples:

POST /faas/key/:key
POST /faas/id/:id

{
  "varName1": {"value":"the Value 1", "type":"String"},
  "varName2": {"value":true, "type":"Boolean"}
}

---

Endpoint Styles

1. faas
2. func
3. function
4. camunda

---

Response handling

1. When Camunda throws an error: If Camunda returns a error then it should be logged and the FaaS API returns a internal server error 500 response.
2. Camunda will return the following:
   1. body
   2. status_code
   3. Headers? (json object?)

FaaS service type will convert this into a proper response.

All processing should be optimized for speed over elegance. Speed of response is priority.

If Camunda does not return the proper variables that Services Microservice will return a Internal Error

---

Considerations

1. How should multiple validations be returned?
   1. body will have array of "errors" will be returned and be the list of errors.
2. When complex logging should occur about errors, have the logging occur async after the response has been returned
3. The Service MS will have to parse stringified json objects into proper json.
4. question: should there be a debug mode (activated through query param) that returns full variable data / the raw response from Camunda?
5. Status codes will have to be converted to proper format.

---

Samples

Variables in Camunda process:

response_body = [] or = {} (is valid JSON)
response_headers = [{"key": "value"}]
response_status_code = integer

For multiple errors:

The response_body would be a SPIN Json array, and each error would append to the array.
For single error response scenarios, the json could return any style defined in the bpmn.

If Function/Process cannot be found then Function not found error response is returned

---

All other variables that would be returned by Camunda would be ignored.

---

Data Flow

1. Validations should occur:
   1. Before Form Load,
   2. Before Form Submit or
   3. After Formio Validations.

This should occur as part of a configuration of the BPM Service.

1. Only Next step is continued if proper status code is returned

example of Usage for:

Before Form Load:

1. Check if user is currently to load this form

Before Form Submit:

1. The user can see the form, but are they allowed to submit the form regardless of formio validations

After Formio Validation:

1. Validate specific data in the form using server side validations beyond that of Formio

Before Form Load, Before Form Submit and After Formio Validation configurations should allow multiple processes to be called. and support weight/order to which they are called. OR at least allow all three options to be implemented. So that a single service can have a Before Load, Before Submit and After Formio processes.

Safe Delete

When we delete a service, the field DeleteAt is filled, but in the API, the result always appears

Add ability to inject custom_data variable into camunda on BPM scenario submission

use the custom_data property that is being added into the config field

DigitalState/Admin#68

Ommitting 'data' attribute from POST /categories causes 500 error.

Disable ability to submit a Service (Create a submission) for disabled services

Disable ability to submit a Service (Create a submission) for disabled services.

Formio Error Handling

1. Formio is offline
2. Formio throws an error (error that is not a normal/expected error)
3. Formio cannot submit

Unable to add new scenarios (probably due to translation updates)

Error:

"detail": "service.title: This value should not be blank.\nservice.description: This value should not be blank.\nservice.presentation: This value should not be blank.\nslug: This value should not be blank.",

This occurs whether POSTing values in single or multiple languages.

Add Data field into Services Get List - ACL issue

The current ACL does not expose the Service's Data field in the Get List for individual.

This is causing an issue were the icons cannot be set for a service based on the icon property in the Date column.

Internal Server Error (500) when any user attempts to list `/services`

In a lab deployment, [email protected] tried to list services and received a Internal Server Error (500) response from the API with an empty array in the body. This happens [email protected] as well.

Add hierarchical categories

Add the ability to have hierarchical categories.

Should allow filtering based on the children

Example:

->Departments:
--->Public Works:
---|--->Roads:
---|---|--->Line Painting

Add "Assistant" service type

The assistant service type is link and information about assistant usage.

A assistant is Google Home, Siri, Amazon Alexa, etc.

Unable to delete services or scenarios

Visibility of Services options

1. Overall Enabled/Disabled toggle
2. Can be seen by
   1. Everyone;
   2. only Staff;
   3. only staff that are members of specific BUs

Add ability to filter services based on the Service Types associated with the Service

Example:

"Show me all services that have API scenarios."

Submission uuid filter does not seem to filter, and returns the entire list of submissions

PUT requests do not update translated fields.

Add ability to filter services based on service categories

Add ability to filter services based on service categories

Add API endpoint to Get BPMN Image when scenario type is BPM and Process ID is provided

Investigate behavior of passing ?title[]=value1&title[]=value2 versus ?title=[value1,value2] and the type-casting issue

Add Information Scenario Type

Add Link Scenario Type

Add default value for the new weight property.

The following error is thrown when attempting to create a new Service.
The same is probably the case with other entities.

{@context: "/app_dev.php/contexts/ConstraintViolationList", @type: "ConstraintViolationList",…}
@context
:
"/app_dev.php/contexts/ConstraintViolationList"
@type
:
"ConstraintViolationList"
hydra:description
:
"weight: This value should not be blank."
hydra:title
:
"An error occurred"
violations
:
[{propertyPath: "weight", message: "This value should not be blank."}]

Allow numbers in form names/paths

Add Service Submission Confirmation API response

1. Data object with various response information

Add ability to use multiple data resolvers in a single form field

possibly use pattern such as: ${ds[bpm].firstName} ${ds[bpm].lastName}

Upgrade to APIP 2.1

Individuals are unable to list Services

When logged in as an Individual (Morgan), I receive a "Access Denied" response when calling http://localhost:8051/app_dev.php/services.

Create a /submissions endpoint for each bpm scenario: services/:id/scenario/:id/submissions

Create a /submissions endpoint for each bpm scenario: services/:id/scenario/:id/submissions

Maintain the current root /submissions endpoint for administrative purposes.

Refactor submission / is valid to contain common logic in the core form component

When owner is omitted, the constraint violation list is empty

Camunda Error Handling

1. Camunda is offline
2. Camunda throws an error
3. ...

Add Service Submission Requirement Support

• Check Submission Requirements on Submission
• Check submission requirements on Scenario load.

Error occurs when creating new Submissions

Tested the Postman example with body:

{
	"scenario": "/scenarios/{SCENARIO_UUID}",
	"data": { 
		"test": "test" 
	},
	"version": 1
}

Error:

{
    "type": "https://tools.ietf.org/html/rfc2616#section-10",
    "title": "An error occurred",
    "detail": "",
    "violations": []
}

Auto-generate the `slug` value when creating new Services

Unable to create new services due to:

@type :"ConstraintViolationList"
hydra:description: "slug: This value should not be blank."

Time / Timezone on default configurations of servers is incorrect

Created a submission through formio at 8:23pm but it shows this time.

add Data field to Services

Data should be translatable

Submitting an empty data object for POST /submissions returns php error due to php array vs object with json_decode

{
"type": "https://tools.ietf.org/html/rfc2616#section-10",
"title": "An error occurred",
"detail": "data.value: "value" must be an object",
"violations": [
{
"propertyPath": "data.value",
"message": ""value" must be an object"
}
]
}

Add Private `Data` Field for system data (eg processDefKey)

May also want to add it to other MSs'

Add Channel field to Service Scenarios

Add Channel field to Service Scenarios.

Channels can be a string for now.

• Exposed Channels in the Services Listing. When GET services each returned service should indicate what Channels are available.
• Enable Services to be filtered by Channels

Sorting services and scenarios by title dose not work

The Postman request uses this format:
/scenarios?order[title]=DESC

which throws a "Notice: Undefined offset: 1" error.

Camunda host configuration is set by default to 172.17.0.1

This would cause the scenario activation to fail if Camunda is running on a Docker container with network settings or if Camunda is running outside Docker's network.

Error when saving an entity in a single language

PUT {{services}}{{environment}}/services/9ed44d24-b2e1-4882-82f9-7e4c2c8bf73d

Request body:

{
  "owner": "BusinessUnit",
  "ownerUuid": "8454c987-cbc5-4a24-ba1a-d420283caabd",
  "slug": "report-pothole",
  "title": {
    "fr": "Signaler un nids de poule"
  },
  "description": {
    "fr": "foobar"
  },
  "presentation": {
    "fr": "Presentation ..."
  },
  "data": {
    "fr": []
  },
  "enabled": true,
  "weight": 1,
  "version": 2
}

Resulting error:

{
    "type": "https://tools.ietf.org/html/rfc2616#section-10",
    "title": "An error occurred",
    "detail": "title[en]: This value should not be blank.\ndescription[en]: This value should not be blank.\npresentation[en]: This value should not be blank.",
    "violations": [
        {
            "propertyPath": "title[en]",
            "message": "This value should not be blank."
        },
        {
            "propertyPath": "description[en]",
            "message": "This value should not be blank."
        },
        {
            "propertyPath": "presentation[en]",
            "message": "This value should not be blank."
        }
    ]
}

Add ability to upload/deploy camunda processes through services MS