{"id":2169,"date":"2022-04-07T14:53:19","date_gmt":"2022-04-07T14:53:19","guid":{"rendered":"https:\/\/info.documotor.com\/?page_id=2169"},"modified":"2023-03-07T09:33:37","modified_gmt":"2023-03-07T09:33:37","slug":"connected-services","status":"publish","type":"page","link":"https:\/\/info.documotor.com\/?page_id=2169","title":{"rendered":"Connected Services"},"content":{"rendered":"\n<p>The concept of a <em><strong>Connected Service<\/strong><\/em> is simple: <em>an external service which we can fetch data from<\/em>.<\/p>\n\n\n\n<p>In order to accomplish this, an <strong>Owner user<\/strong> has to set up the <strong>Operations <\/strong>they want to interact with, and the <strong>Authorization <\/strong>required (if needed) to access them.<br>In other words, similar to its software counterpart, a <em>connected service<\/em> is the abstraction of a set of <em>operations <\/em>that belong under the same logical group and share the same access (<em>owners<\/em>) and <em>authorization <\/em>policies.<\/p>\n\n\n\n<p>Once set up, a service can be requested from JMES transformations (e.g. <em>Templates<\/em>, <em>Custom Functions<\/em>) using the <a rel=\"noreferrer noopener\" href=\"https:\/\/info.documotor.com\/?page_id=282#service\" target=\"_blank\"><em>service<\/em> function<\/a>, with the service name, operation name and payload as parameters.<br><em>For example:<\/em> <code>service('ThisIsAService', 'OperationA', &lt;payload_data&gt;)<\/code><br>will call <em>OperationA <\/em>defined in <em>ThisIsAService <\/em>and send the <em>payload_data<\/em>.<\/p>\n\n\n\n<h2 id=\"operations\">Operations<\/h2>\n\n\n\n<p>Essentially an <em>endpoint<\/em>, <strong>Operations <\/strong>are the core element behind Connected Services.<br>Each of them consist of 4 elements:<\/p>\n\n\n\n<ul><li><b><em><strong>Name<\/strong><\/em><\/b><br>Easily identifiable name for the operation.<\/li><li><b><em><strong>HTTP Method<\/strong><\/em><\/b><br>Currently, only GET and POST are available. For GET requests the <em>payload_data <\/em>is appended as query parameters to the URL. For POST requests the <em>payload_data <\/em>is inserted into the body of the request.<\/li><li><b><em><strong>URL<\/strong><\/em><\/b><br>Endpoint URI to be consumed.<\/li><li><b><em><strong>Response Type<\/strong><\/em><\/b><br>&#8220;Suggested&#8221; way for the response data to be interpreted as when there&#8217;s no content type specified.<\/li><\/ul>\n\n\n\n<div class=\"wp-block-columns\">\n<div class=\"wp-block-column\" style=\"flex-basis:100%\">\n<figure class=\"wp-block-image size-full is-resized\"><img loading=\"lazy\" src=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/service_operation.png\" alt=\"\" class=\"wp-image-2176\" width=\"858\" height=\"369\" srcset=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/service_operation.png 858w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/service_operation-300x129.png 300w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/service_operation-768x330.png 768w\" sizes=\"(max-width: 858px) 100vw, 858px\" \/><\/figure>\n<\/div>\n<\/div>\n\n\n\n<h2 id=\"authorization\">Authorization<\/h2>\n\n\n\n<p>In many cases, some sort of Authorization is required to interact with the operations.<br>Currently, 3 types are supported:<\/p>\n\n\n\n<ul><li><strong>None<\/strong><\/li><li><strong>Static Header<br>Key-Value<\/strong> combination sent as a Header.<br>Can be used for other types, such as <em>API Key<\/em>, <em>Bearer Token<\/em>, <em>Basic Auth<\/em>, etc.<\/li><li><strong>OAuth2 Client Credentials (WSO2)<\/strong><br><strong>Client Credentials Grant<\/strong> for WSO2 API Manager.<br>Requires <em>Consumer Key<\/em> (Client ID), <em>Consumer Secret<\/em> (Client Secret), <em>Token API URL<\/em>, and <em>Token Header Prefix<\/em> (default <code>Basic<\/code>).<\/li><li><strong>OAuth2 Password Credentials<\/strong><br>Requires <em>Consumer Key (Client ID), Consumer Secret (Client Secret), Token API URL, Username and Password.<\/em><\/li><\/ul>\n\n\n\n<figure class=\"wp-block-image size-full\"><img loading=\"lazy\" width=\"849\" height=\"250\" src=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/07\/image-2.png\" alt=\"\" class=\"wp-image-2865\" srcset=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/07\/image-2.png 849w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/07\/image-2-300x88.png 300w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/07\/image-2-768x226.png 768w\" sizes=\"(max-width: 849px) 100vw, 849px\" \/><\/figure>\n\n\n\n<p>As long as it is not saved, it is possible to change the Type without affecting the service or currently running operations.<br>Once you do, this Auth will be then used with all the Operations in the Service.<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">As <strong>Authorization <\/strong>handles <em><strong>sensible data<\/strong><\/em>, it is <mark style=\"background-color:rgba(0, 0, 0, 0)\" class=\"has-inline-color has-vivid-red-color\"><strong>NOT preserved<\/strong><\/mark> during <em>Backup <\/em>operations.<\/pre>\n\n\n\n<h2 id=\"owners\">Owners<\/h2>\n\n\n\n<p>Owners are users granted permission to make changes to the Service, identified by their registered email.<br>All owners share the same level of privileges, but the current user cannot remove themselves.<\/p>\n\n\n\n<figure class=\"wp-block-image size-full\"><img loading=\"lazy\" width=\"864\" height=\"326\" src=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/service_owners.png\" alt=\"\" class=\"wp-image-2189\" srcset=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/service_owners.png 864w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/service_owners-300x113.png 300w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/service_owners-768x290.png 768w\" sizes=\"(max-width: 864px) 100vw, 864px\" \/><\/figure>\n\n\n\n<h3 id=\"non-owners\">Non-Owner Users<\/h3>\n\n\n\n<p>When an User is not included as an Owner on a specific Service, they <em>can still interact with it<\/em>, but <strong>not make changes<\/strong>. This means:<\/p>\n\n\n\n<p><strong>a<\/strong>. They are allowed to call the Service and any of its Operations using <em>JMES&#8217;s <a href=\"https:\/\/info.documotor.com\/?page_id=282#service\" target=\"_blank\" rel=\"noreferrer noopener\">service function<\/a><\/em>.<br><strong>b<\/strong>. They get a very simplified (read-only) list of Operations when accessing the Service itself.<\/p>\n\n\n\n<figure class=\"wp-block-image size-full\"><img loading=\"lazy\" width=\"869\" height=\"173\" src=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/service_notOwner.png\" alt=\"\" class=\"wp-image-2190\" srcset=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/service_notOwner.png 869w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/service_notOwner-300x60.png 300w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/service_notOwner-768x153.png 768w\" sizes=\"(max-width: 869px) 100vw, 869px\" \/><\/figure>\n\n\n\n<h2 id=\"result\">Result<\/h2>\n\n\n\n<h3>Errors<\/h3>\n\n\n\n<p>Since a Connected Service is called as a JMES function, when an error or invalid response is recieved, it is shown as a standard JMES error toast.<\/p>\n\n\n\n<h3>Success and Type Parsing<\/h3>\n\n\n\n<p>How the response is interpreted depends on both the <em>response&#8217;s Content-Type<\/em> and the user-supplied <em>Response Type<\/em> (see <code>Operations<\/code>): Priority goes to the Content-Type, and only when it is set as &#8220;any&#8221; MIME-type (<code>*\/*<\/code>) or is not defined does the user&#8217;s take place.<\/p>\n\n\n\n<p>Currently, response content is handled in 3 ways:<br><strong>Plain Text<\/strong> &#8211; <em>Text<\/em> (<code>text\/*<\/code>), <em>XML <\/em>(<code>application\/xml<\/code>)<br><strong>JSON <\/strong>&#8211; <em>JSON <\/em>(<code>application\/json<\/code>)<br><strong>Base64 string<\/strong> &#8211; <em>Images <\/em>(<code>image\/*<\/code>), <em>OpenXML <\/em>(<code>application\/vnd.openxmlformats.*<\/code>), <em>other binary data<\/em>.<\/p>\n\n\n\n<h2 id=\"examples\">Examples<\/h2>\n\n\n\n<h3>Basic example<\/h3>\n\n\n\n<div class=\"wp-container-1 wp-block-group\"><div class=\"wp-block-group__inner-container\">\n<figure class=\"wp-block-image size-large\"><img loading=\"lazy\" width=\"1024\" height=\"210\" src=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_7iQ9b8jU5F-1024x210.png\" alt=\"\" class=\"wp-image-2200\" srcset=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_7iQ9b8jU5F-1024x210.png 1024w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_7iQ9b8jU5F-300x61.png 300w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_7iQ9b8jU5F-768x157.png 768w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_7iQ9b8jU5F.png 1075w\" sizes=\"(max-width: 1024px) 100vw, 1024px\" \/><figcaption>Non-owner view<\/figcaption><\/figure>\n\n\n\n<figure class=\"wp-block-image size-large\"><img loading=\"lazy\" width=\"1024\" height=\"79\" src=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_YejXc5TYXZ-1024x79.png\" alt=\"\" class=\"wp-image-2201\" srcset=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_YejXc5TYXZ-1024x79.png 1024w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_YejXc5TYXZ-300x23.png 300w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_YejXc5TYXZ-768x59.png 768w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_YejXc5TYXZ.png 1050w\" sizes=\"(max-width: 1024px) 100vw, 1024px\" \/><figcaption>Example call to service<\/figcaption><\/figure>\n\n\n\n<figure class=\"wp-block-image size-large\"><img loading=\"lazy\" width=\"1024\" height=\"357\" src=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_p2JDOaqeYh-1024x357.png\" alt=\"\" class=\"wp-image-2202\" srcset=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_p2JDOaqeYh-1024x357.png 1024w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_p2JDOaqeYh-300x105.png 300w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_p2JDOaqeYh-768x268.png 768w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/firefox_p2JDOaqeYh.png 1050w\" sizes=\"(max-width: 1024px) 100vw, 1024px\" \/><figcaption>JSON response<\/figcaption><\/figure>\n<\/div><\/div>\n\n\n\n<h3>Comparison with Postman<\/h3>\n\n\n\n<p><a rel=\"noreferrer noopener\" href=\"https:\/\/www.postman.com\/\" data-type=\"URL\" data-id=\"https:\/\/www.postman.com\/\" target=\"_blank\">Postman<\/a> served as the base structure for Connected Services, as can be seen in this simple case based on the previous example:<\/p>\n\n\n\n<figure class=\"wp-block-image size-full\"><img loading=\"lazy\" width=\"832\" height=\"668\" src=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/Postman_hui0s6jpA8.png\" alt=\"\" class=\"wp-image-2198\" srcset=\"https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/Postman_hui0s6jpA8.png 832w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/Postman_hui0s6jpA8-300x241.png 300w, https:\/\/info.documotor.com\/wp-content\/uploads\/2022\/04\/Postman_hui0s6jpA8-768x617.png 768w\" sizes=\"(max-width: 832px) 100vw, 832px\" \/><figcaption>Example Postman Echo endpoint<\/figcaption><\/figure>\n","protected":false},"excerpt":{"rendered":"<p>The concept of a Connected Service is simple: an external service which we can fetch data from. In order to accomplish this, an Owner user has to set up the Operations they want to interact with, and the Authorization required (if needed) to access them.In other words, similar to its software counterpart, a connected service [&hellip;]<\/p>\n","protected":false},"author":16,"featured_media":0,"parent":3160,"menu_order":8,"comment_status":"closed","ping_status":"closed","template":"","meta":[],"_links":{"self":[{"href":"https:\/\/info.documotor.com\/index.php?rest_route=\/wp\/v2\/pages\/2169"}],"collection":[{"href":"https:\/\/info.documotor.com\/index.php?rest_route=\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/info.documotor.com\/index.php?rest_route=\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/info.documotor.com\/index.php?rest_route=\/wp\/v2\/users\/16"}],"replies":[{"embeddable":true,"href":"https:\/\/info.documotor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=2169"}],"version-history":[{"count":15,"href":"https:\/\/info.documotor.com\/index.php?rest_route=\/wp\/v2\/pages\/2169\/revisions"}],"predecessor-version":[{"id":2870,"href":"https:\/\/info.documotor.com\/index.php?rest_route=\/wp\/v2\/pages\/2169\/revisions\/2870"}],"up":[{"embeddable":true,"href":"https:\/\/info.documotor.com\/index.php?rest_route=\/wp\/v2\/pages\/3160"}],"wp:attachment":[{"href":"https:\/\/info.documotor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=2169"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}