From a08e107859d475d3a52ff3e598d2029fcfed017c Mon Sep 17 00:00:00 2001 From: joostverhoog Date: Tue, 3 Jul 2018 08:45:50 +0200 Subject: [PATCH] Integration changes for 7.16 (#1219) * Feature/deprecated operation (#1) * Is Deprecated ref guide * Update open-api operation * Update versioning doc * Update version-rest-service.md * Update open-api.md * Update published-rest-operation.md * Update version-rest-service.md * Update open-api.md * Documentation and example value in message definitions * Updated documentation about proxy information in REST consume and about default content-type. * A bit more detail about date/time format * Updated the image for call-rest-action * Publish a microflow as a REST operation * A message definition now has a unique name * Added documentation for deprecated web service client setting (#3) * Added documentation for deprecated web service client setting * Project setting 'Web service calls' * Schema validation is not possible when using the new implementation for web service calls (#4) * REST Access Tab (#2) * Feature/deprecated operation (#1) * Is Deprecated ref guide * Update open-api operation * Update versioning doc * Update version-rest-service.md * Update open-api.md * Update published-rest-operation.md * Update version-rest-service.md * Update open-api.md * REST Access Tab * Typos * Re-worded rest access * Rest Access * Update index * Remove Allowed Roles * Added documentation about proxy settings in webservice call action (#5) * Review of release notes for 7.15 * Update call-rest-action.md * Update call-web-service-action.md * Update message-definition.md * Update module-security.md * Update open-api.md * Update project-settings.md * Update publish-microflow-as-rest-operation.md * Update published-rest-operation.md * Update published-rest-services.md * Generate mapping(s) button on the message definitions list * Generating REST operations (#7) * Update version-rest-service.md * Update call-web-service-action.md * Update generate-rest-resource.md * Update message-definitions.md * Update module-security.md * Update project-settings.md * Update generate-rest-resource.md * Update publish-microflow-as-rest-operation.md * Update published-rest-services.md * Update published-rest-services.md --- .../howto/integration/version-rest-service.md | 10 ++-- content/refguide/call-web-service-action.md | 2 +- content/refguide/generate-rest-resource.md | 48 +++++++++++++++++++ content/refguide/message-definitions.md | 4 ++ content/refguide/module-security.md | 2 +- content/refguide/project-settings.md | 2 +- .../publish-microflow-as-rest-operation.md | 12 ++--- content/refguide/published-rest-service.md | 2 + content/refguide/published-rest-services.md | 6 ++- 9 files changed, 73 insertions(+), 15 deletions(-) create mode 100644 content/refguide/generate-rest-resource.md diff --git a/content/howto/integration/version-rest-service.md b/content/howto/integration/version-rest-service.md index 815059263d7..21fe78a82bf 100644 --- a/content/howto/integration/version-rest-service.md +++ b/content/howto/integration/version-rest-service.md @@ -23,9 +23,9 @@ Give each service a version number following the `MAJOR.MINOR.PATCH` format: To make versioning more explicit in your model, we suggest creating a folder for each service. Call it *ServiceName_Version*. Store all microflows, mappings, and message definitions that are used in the service in that folder. -After you have published a service and clients are using it, it is not advisable to change it anymore. +After you have published a service and users are using it, it is not advisable to change it anymore. -If you were to change it in a way that requires the clients to change, you would introduce a "breaking change." A client would start getting errors without doing anything different. +If you were to change it in a way that requires the user to change, you would introduce a "breaking change." The user would start getting errors without doing anything different. Instead of changing a published service, you should duplicate the service and give it a new major version. If you want to change a microflow, a mapping, or a message definition, duplicate that as well, and change the duplicate. @@ -94,8 +94,8 @@ Note that this is a breaking change (because it is not backwards compatible), so After you have created a new version of your service, you should mark the old version as deprecated. -You do that by adding **(deprecated)** to the service name. Write a description of why it was deprecated and what the new version number is in the **Public documentation** of the service. You should also mark all operations that changed as deprecated. In this way, clients can see which operations have changed from one version to the next. +You do that by adding **(deprecated)** to the service name. Write a description of why it was deprecated and what the new version number is in the **Public documentation** of the service. You should also mark all the operations that changed as deprecated. This way, the user can see which operations have changed from one version to the next. -You should let clients know that the this version is deprecated (for instance, by publishing release notes). +You should let users know that the this version is deprecated (for instance, by publishing release notes). -After a version has been deprecated for a sufficiently long time, you can remove it. All the clients should have moved to the new version in the meantime. +After a version has been deprecated for a sufficiently long time, you can remove it. All users should have moved to the new version in the meantime. diff --git a/content/refguide/call-web-service-action.md b/content/refguide/call-web-service-action.md index a1ecd49aee3..6e06e03933d 100644 --- a/content/refguide/call-web-service-action.md +++ b/content/refguide/call-web-service-action.md @@ -39,7 +39,7 @@ When calling a web service using a call-web-service activity, the location of th ### 2.4 Use Timeout on Request -**Use Timeout on Request** can be used to throw an exception when the web service takes too long to respond after connecting. After a set amount of time an exception will be thrown and the microflow will rollback or go into your custom error handler. Note that this does not change the connection timeout. +This can be used to throw an exception when the web service takes too long to respond after connecting. After a set amount of time, an exception will be thrown and the microflow will roll back or go into your custom error handler. Note that this does not change the connection timeout. _Default value:_ No diff --git a/content/refguide/generate-rest-resource.md b/content/refguide/generate-rest-resource.md new file mode 100644 index 00000000000..6bf501b0d56 --- /dev/null +++ b/content/refguide/generate-rest-resource.md @@ -0,0 +1,48 @@ +--- +title: "Generating a REST Resource" +parent: "published-rest-services" +--- + +{{% alert type="info" %}} + +This feature was introduced in version 7.16.0. + +{{% /alert %}} + +## 1 Introduction + +You can publish a REST resource with basic operations based on an entity by right-clicking an entity in the domain model and selecting **Expose as REST resource**. Alternatively, you can drag an entity or message definition onto the list of resources of a published REST service. This page describes the options you have once you perform one of these actions. + +## 2 REST Service + +This only shows up when you click **Expose as REST resource** in the domain model. Next, choose a service in which to generate the resource and operation. + +## 3 General + +### 3.1 Resource Name + +Type the name of the resource that you want to publish. + +### 3.2 Key Attribute + +To be able to create a **Get by key** or a **Delete** operation, there needs to be a unique attribute on the entity. Select that attribute here. + +## 4 Operations + +Check the operations that you want to generate: + +* **Get all** – allows clients to get all the objects +* **Get by key** – allows clients to get an object, given its key +* **Post** – allows clients to add a new object +* **Delete** – allows clients to delete objects + +When you click **OK**, the following items are created: + +* A resource +* All the operations that you selected +* A microflow for each operation +* A message definition +* An import mapping (for the **Post** operation) +* An export mapping (for the **Get all** and **Get by key** operations) + +If you have already created a message definition for the entity, that message definition will be reused. Existing import and export mappings based on that message definition will also be reused. diff --git a/content/refguide/message-definitions.md b/content/refguide/message-definitions.md index a6c3e0bf5dc..c3be6494160 100644 --- a/content/refguide/message-definitions.md +++ b/content/refguide/message-definitions.md @@ -17,6 +17,10 @@ Message definitions define the structure of the messages that are sent from and In the list of message definitions, you can add, edit, or delete a [message definition](message-definition) or find their usages. +### 2.1 Generate Mapping(s) + +The **Generate mapping(s)** button allows you to generate an import and/or an export mapping for the selected message definition. + ## 3 Documentation Use the documentation to describe what the message definitions are used for. diff --git a/content/refguide/module-security.md b/content/refguide/module-security.md index 758e4e93b5c..c4a6d448ae0 100644 --- a/content/refguide/module-security.md +++ b/content/refguide/module-security.md @@ -41,7 +41,7 @@ Entity Access takes the form of a large matrix showing access rules that apply t OData Access defines for each module role whether users with this role are authorized to access OData resources for each OData service exposed within the module. -OData Access takes the shape of a large matrix showing published OData services and modules roles. For each combination you can indicate whether or not the module role has access to the published OData service. You can also edit this information in [published OData services](published-odata-services) using the **Allowed roles** property in the **Settings** tab. +OData Access takes the shape of a large matrix showing published OData services and modules roles. For each combination, you can indicate whether the module role has access to the published OData service. You can also edit this information in [published OData services](published-odata-services) using the **Allowed roles** property in the **Settings** tab. ## 6 REST Access diff --git a/content/refguide/project-settings.md b/content/refguide/project-settings.md index 65e9cd8a942..c30a407e6aa 100644 --- a/content/refguide/project-settings.md +++ b/content/refguide/project-settings.md @@ -162,7 +162,7 @@ This setting was added in version 7.15 {{% /alert %}} -We optimize the way web services are called, which means that you can use custom proxy settings for each web service call. However, this implementation does not support schema validation yet. Neither does it support complex schemas that use a policy reference with an algorithm suite. This configuration option allows you to use the old implementation, in case you need one of these features. +The way web services are called has been optimized, which means that you can use custom proxy settings for each web service call. However, this implementation does not support schema validation, nor does it support complex schemas that use a policy reference with an algorithm suite. This configuration option allows you to use the old implementation, in case you need one of these features. ## 4 Modeler diff --git a/content/refguide/publish-microflow-as-rest-operation.md b/content/refguide/publish-microflow-as-rest-operation.md index 89a122387a1..619370cb26d 100644 --- a/content/refguide/publish-microflow-as-rest-operation.md +++ b/content/refguide/publish-microflow-as-rest-operation.md @@ -1,5 +1,5 @@ --- -title: "Publishing a Microflow as REST Operation" +title: "Publishing a Microflow as a REST Operation" parent: "published-rest-services" --- @@ -11,19 +11,19 @@ This feature was introduced in version 7.15.0. ## 1 Introduction -To publish a microflow as a REST service operation, right-click anywhere in the whitespace of the microflow and select **Publish as REST service operation**. +To publish a microflow as a REST service operation, right-click in the microflow editor and select **Publish as REST service operation**. -Notice that if the microflow takes more than one parameter of an object or list type, it can't be published as a REST operation. If you try to publish it, there will be a consistency error. +Notice that if the microflow takes more than one parameter of an object or list type, it cannot be published as a REST operation. If you try to publish it, there will be a consistency error. ## 2 Choosing a Resource -After you have clicked **Publish as REST service operation**, you will need to select a resource under which to publish the microflow. There are several options: +After you click **Publish as REST service operation**, you need to select a resource under which to publish the microflow. There are several options: * If you already have a service and a resouce under which to publish the microflow, select it and click **Select** * If you already have a service but you want to create a resource, select the service and click **New** -* If you want to create a new service, select a module or a folder and click **New** +* If you want to create a new service, select a module or folder and click **New** -The suggested name of the resource is the entity of a parameter of the microflow, or the entity result of the microflow. +The suggested name of the resource is the entity of a parameter of the microflow or the entity result of the microflow. ## 3 Editing the Operation diff --git a/content/refguide/published-rest-service.md b/content/refguide/published-rest-service.md index 7217b79b6b9..5262d13d7d8 100644 --- a/content/refguide/published-rest-service.md +++ b/content/refguide/published-rest-service.md @@ -122,6 +122,8 @@ The allowed roles define which [module role](module-role) a user must have to be A REST service exposes a number of [resources](published-rest-resource). On a resource you can define GET, PUT, POST, PATCH, DELETE, HEAD and OPTIONS operations. +You can drag an entity or a message definition onto this list to [generate a complete resource](generate-rest-resource). + ## 5 Operations When you select a resource, you see the [operations](published-rest-operation) that are defined for that resource. diff --git a/content/refguide/published-rest-services.md b/content/refguide/published-rest-services.md index 284a6940475..b24cee9e9eb 100644 --- a/content/refguide/published-rest-services.md +++ b/content/refguide/published-rest-services.md @@ -15,7 +15,11 @@ Add a [published REST service](published-rest-service) to expose your entities a ## 2 Published REST Service -For an overview of the available options when you add a published service, see [Published REST Service](published-rest-service). +For an overview of the available options when you add a published service, see [Published REST Service](published-rest-service). + +You can easily expose an entity via REST by right-clicking the entity in the [domain model](domain-model) and selecting [Expose as REST resource](generate-rest-resource). + +To publish a microflow as a REST operation, right-click anywhere in the editor and select [Publish as REST service operation](publish-microflow-as-rest-operation). To publish a microflow as a REST operation, right-click anywhere in the editor and select [Publish as REST service operation](publish-microflow-as-rest-operation).