What are Capsules?

Capsules are a new and great Digibee functionality, part of the Digibee HIP Platform. The Digibee Capsules are reusable components that can be created by any Platform user by applying the same visual development model conceived in the pipeline creation, providing a reusable, secure, validated and evolving business logic.

A Capsule allows the flow integration to be published in the components palette to be used in another moment, in an even simpler and quicker way.

It's like the components available in the Platform were atoms and the Capsules were molecules that group the atoms into more complex tasks to solve a specific issue.

Why to use Capsules?

The Capsule is a powerful tool to modularize business logics and, given that, it eases the knowledge sharing and the services exposition inside your company. It's a great facilitator for the system architects that work with the Platform, since it became easier to modularize business functions and standardize its use inside the environment, decreasing the building time and keeping the quality standard.

The Capsules also open the door for a new work strand in the Platform, once this functionality will allow a real ecosystem to be developed and promote the knowledge and services exchange between the companies.

How to use Capsules?

To use a Capsule inside the Digibee Platform, just access it from the main menu, click on the CREATE button to create a new Capsule and then build a logic with the Digibee Platform interface you already know.

Capsule

The Capsule is composed of some elements that provide support for its construction, organization and visualization. These are they:

  • Header
  • Collection
  • Group
  • Capsule
  • Components
  • Test-Mode
  • Publishing
  • Versioning
  • Archived

Example:

Header

The header exists to previously store the image options to be used in the Capsule component representation in the pipeline canvas.

See an example of a component with the header:

The process of a header creation is made along with the process to save a Collection. By then, you can select a header from a list or choose to create a new header.

The permissions created to manage and access the items are:

  • CAPSULE:CREATE:HEADER - allows the register of new headers to be used in the creation of Collections.
  • CAPSULE:READ:HEADER - allows the visualization and choice of headers for the registration of a new Collection.

Collection

Collection is the repository where the Capsules are stored. Consequently, all the Capsules need a Collection.

Curiosity: during the beta phase, we realized that it's common for the Collections to be represented by systems, such as ERP, CRM, etc., or by business areas.

It's possible to create as many Collections as you need or want, but we recommend to always check if there's a Collection already available. So, when you decide to create a new Collection, decide what you're going to name it. For example, in a company the Collections are defined based on the name of systems, but for some others it can be more interesting to define the name of a Collection considering the name of a business area.

The process to create a new Collection is made along with the process to save its Capsule. By then, you can select a Capsule from a list or choose to create a new Capsule.

If you choose to create a new Collection, the following form will be displayed:

The permission created to manage and access the item is:

  • CAPSULE:CREATE - allows the creation of new Collections.

Group

Group is an organizer of Capsules inside a Collection.

Curiosity: during our beta phase, we realized the need for this organizational item. For example, a SAP Collection can have many Capsules and they can be organized based on the modules of this system, such as Sales, Financial, among others.

Groups are organizational items that live inside a Collection.

The process to create a Groups is made along with the process to save its Capsule. By then, you can select a Group from a list or choose to create a new Group.

The permissions created to manage and access the item are:

  • CAPSULE:CREATE:GROUP - allows the registration of new Groups to be used in the creation of Capsules.
  • CAPSULE:READ:GROUP - allows the visualization and choice of a Group for the registration of a new Capsule.

Configurations - Parameters

The input parameters are shown during the use of the Capsule on pipeline canvas.

Tip: the input parameters are similar to the fields already presented in the core components. For example, the URL of REST or the condition of Choice.

With this resource, the developer is totally free to define the parameters and also to document the Capsule use guidance.

The input parameters are your contract of use, which means, which parameters can and must be provided to attend the requirements demanded by the Capsule and used by any component present in the Capsule.

By accessing the configuration menu, it's possible to find the input parameters definitions.

Tip: the form displayed by this point is just a filling example that we make available to help you to understand and learn. We recommend you to make a quick analysis of the example, delete the information in it and insert your own data.

See below an example with 4 different configuration types (TEXT, SELECT TOGGLE and TAGS).

Observe the Form Preview item, which is being shown on the left. This resource is very helpful in the creation of the parameters form, because it's used in real time while you add, change and organize your choices.

How to use the parameters declared in this section in the canvas components?

In the image above, the “Property” field has been filled with the id, productType, status and tags values.

See how to use Double Braces expressions to access the values:

{{ capsule.id }} 
{{ capsule.productType }}
{{ capsule.status }}
{{ capsule.tags }}

Tip: all the possible options in Double Braces are valid for this new resource {{ capsule... }}. Use them in a combination with the functions. Click here to read our article about this topic.

Configurations - Accounts

Account is a functionality used by core components (for example, REST) to make authentication in the endpoints. To use an Accounts, just find the Accounts list in the pipeline canvas screen, that comes straight from the Realm and are managed in the Configurations > Accounts menu.

In the Capsules, this functionality has a minor difference in relation to the pipeline that will use it, since Accounts and pipelines aren't in the same construction Realm at all times. Therefore, it's necessary to previously define a Accounts Placeholder list. This list can be defined in the Capsules screen by clicking on:

Configurations in the screen > Accounts tab

In the screen described above will be defined the Accounts with Label and the description to guide about the type of Account that must be selected inside the pipeline canvas.

In the example of the screen above, SAP Account is the placeholder presented to the Capsule user that, in turn, must choose an Account that has valid information to access SAP. That way, the credentials remain outside the Capsule, bringing more security for its use.

See below how the core component looks like when configured inside the Capsule and how the visualization form in test-mode looks like:

Test-mode

Configurations - Documentation

This is an internal area of the Capsule and must be used to register detailed and relevant information about how it works and for future maintenance.

The content is exclusive for the Capsule developers of your Realm. Therefore, it's not presented to the Capsule user.

To access this area, click on the Documentation tab, that is inside Configurations.

Tip: this is a free text area, but we recommend the use of markdown.

Configurations - Contract

Contract is a configuration created to guarantee that the structure of the data from the Capsule execution will always correspond to the JSON Schema defined by your developer.

This configuration is mandatory for the publication. So, it's necessary to define the JSON Schema that corresponds to the Capsule outputs. A well-defined JSON Schema brings more reliability for those who use the Capsule.

IMPORTANT: changes in the JSON Schema that result in contract breach make the Capsule change its version automatically and, consequently, guarantees that the pipelines don't get affected, Read more about versioning in its respective section of this document.

Components

The components that can be used in the Capsules implementation are not only displayed in the palette on the right of the canvas, but also in the pipeline screen.

Only core components are supported. Among them, these aren't supported:

  • Object Store
  • Digibee Storage
  • Relation

Test-Mode

This is a frequently used functionality in the construction of pipelines, through which input data used to run the tests are informed and where the execution results are shown.

An additional column is presented in the Capsule, in which the filling of the parameters defined in the configurations area is requested. Since the tests represent a valid execution, the Capsule developer has the same experience that the future user will have in the pipeline canvas.

Publishing

The building process of a Capsule is sophisticated. Therefore, to make something reusable, we have more responsibilities and care to be taken.

We've created a life cycle to support the construction and maintenance, guaranteeing total freedom to the developer and not affecting the user of the same pipeline.

This cycle is managed by 2 status:

  • Development - where all the Capsules come from. When a Capsule is in this status, no other user visualizes its version.
  • Published - for a Capsule to be in this status, the developer must attend all the mandatory requirements and execute the publishing action.

To make this action, follow these steps:

  • Access the Capsule Menu;
  • Click on the rocket icon or on the Capsule Canvas screen;
  • Click on the PUBLISH button;

Example of a Capsule that haven't had all the requirements attended and can't be published:

Example of a Capsule that had all the requirements attended and can be published:

Obs.: if none of the options above is displayed, consult the access manager of your company and request the inclusion of the CAPSULE:UPDATE:PUBLISH permission.

Versioning

To guarantee trust in the Capsules updates, Digibee has adopted a versioning control composed of 3 levels. When the versions must be updated, the Digibee HIP Platform makes the automatic analysis of a Capsule and determines which the level values will be.

These are the 3 versioning levels:

  • Major: version of the Capsule when a configuration item (input or output) is deleted or becomes mandatory. This version is also applicable when the Capsule contract is totally changed. The redirecting to this version is automatically made by the Platform itself.
  • Minor: version of the Capsule when a configuration item (input or output) is added or becomes optional. This change isn't considered “Major” yet.
  • Fix: version of the Capsule when no impactful changes are made in the pipelines that use it. This change isn't considered “Major” or “Minor”.

It's important to know that these changes are made only if the version being changed had been published before. For example, if you create a Capsule, it will initially get the "1.0.0" version. If it doesn't get published, this version will never be changed when updated are made on it.

After publishing the Capsule, the “1.0.0” version will be defined as no editable. So, when a new update is made in the same Capsule, the Platform will check what's been changed to determine if the version number will be added to the Major, Minor or Fix.

The display of the versions is similar to the one for the pipeline:

Archive

When necessary, it's possible to archive the Capsules through the Archive icon presented in the Capsules list. See below:

To see the list of archived Capsules, use the Archived filter in the search bar:

The archive of a published Capsule that is being used in a pipeline doesn't affect its functioning. It only prevents new users from using the Capsule.

Did this answer your question?