3 posts tagged with "configurator"

This guide explains how to start a new configuration, and update it, using the configurator API. It will also explain how this configuration can be added to a (new) quotation.

1. Retrieve your configuration models​

To ensure successful configuration, start by identifying the model you want to configure. You can retrieve a list of all available configuration models by sending the following request:

GET: https://api.elfsquad.io/configurator/3/configurator/configurationmodels

The response will look something like the following:

{
  "categories": [],
  "features": [
    {
      "featureModelId": "32915340-0924-409b-a938-f7024b3d883a",
      "featureId": "dbe93c07-198c-449f-9f22-91c529a4d060",
      "articleCode": "abc",
      "name": "Product 1"
    }
  ],
  "language": "en"
}

The featureModelId property, which uniquely identifies the configuration model, is essential for the next step. For more information about the response object, refer to the provided api documentation. https://docs.elfsquad.io/docs/spec/configurator/get-configuration-models.

2. Start a new configuration​

Now that we know the id of our model, we can start a new configuration. This can be achieved by sending the following request:

POST: https://api.elfsquad.io/configurator/3/configurator/new/{featureModelId}

The featureModelId in this request is the same as the one retrieved in the previous step. Note: the id can also be found in the EMS. It is also possible to send a body containing startup requirements when starting a new configuration. This body must have the following format:

{
  "startupRequirements": [
    {
      "nodeId": "123e4567-e89b-12d3-a456-426614174000",
      "type": 0,
      "value": 0
    },
    {
      "nodeId": "123e4567-e89b-12d3-a456-426614174001",
      "type": 1,
      "value": 10
    },
    {
      "nodeId": "123e4567-e89b-12d3-a456-426614174002",
      "type": 2,
      "value": "Some text"
    },
     {
      "nodeId": "123e4567-e89b-12d3-a456-426614174003",
      "type": 3,
      "value": 5
    }
  ]
}

Property explanation:

• nodeId: The id of the node you want to change.
• type & value: We currently support 3 different types:
  1. Selection(0): When using a selection type requirement, sending a value of 0 will turn the specified node off. Any other value will turn the node on and change the value to the provided value. Only numeric values are supported.
  2. Value(1): When using a value type requirement, the specified node will turn on (if not on already) and will have it's value changed to the provided value. Even when the value is 0. Only numeric values are supported.
  3. Text(2): When using a text type requirement, the specified node will have it's textValue changed to the provided value. Only string values are supported.
  4. Cardinality(3): When using a cardinality requirement, the specified linkedmodel node will have the specified amount off instances.

The response body will contain the id of the newly created configuration. This id is needed for the other steps. For more information about the request and response bodies, refer to the provided api documentation. https://docs.elfsquad.io/docs/spec/configurator/start-configuration-session.

3. Updating the configuration​

For further configuration changes, you can also utilize the configurator API. However, if you possess all required modifications beforehand, consider using the startup requirements covered earlier for optimal performance. Updating numeric values can be done by sending the following request:

PUT: https://api.elfsquad.io/configurator/3/configurator/{configurationId}/multiple

Note that configurationId is the id of the configuration created in the previous step. The request should contain a JSON body with an array of requirements that have the following format:

[
  {
    "featureModelNodeId": "ad1e70a3-199a-4363-9b12-40472c568135",
    "value": 0,
    "isSelection": true
  },
  {
    "featureModelNodeId": "ad1e70a3-199a-4363-9b12-40472c568136",
    "value": 5,
    "isSelection": false
  }
]

Property explanation:

• featureModelNodeId: The id of the node that has to be updated.
• value: The value that has to be assigned to the specified node. Only numeric values are supported.
• isSelection: When set to true, the requirement will behave like a selection type requirement from the previous step. Otherwise it will act like a value type requirement.

A slightly different request has to be sent when updating text values:

PUT: https://api.elfsquad.io/configurator/3/configurator/{configurationId}/text/multiple

The JSON body is also slightly different:

[
  {
    "featureModelNodeId": "ad1e70a3-199a-4363-9b12-40472c568135",
    "textValue": ""
  },
  {
    "featureModelNodeId": "ad1e70a3-199a-4363-9b12-40472c568136",
    "textValue": "Example Text"
  }
]

Property explanation:

• featureModelNodeId: The id of the node that has to be updated.
• textValue: The text value that has to be assigned to the specified node. Only string values are supported.

For more information regarding the request and response bodies, refer to the provided api documentation. https://docs.elfsquad.io/docs/spec/configurator/update-requirement.

4. Creating a new quotation​

Before you can add the properly adjusted configuration to a quotation, you have to create a new quotation. This can be done using our quotation api. The api will automatically assign the correct quotation status and quotation number. This can be done by sending the following request:

POST: https://api.elfsquad.io/quotation/1/quotations

This request requires a JSON body with optional properties. The response body will contain the id of the newly created quotation. For more information about the request and response bodies, refer to the provided api documentation. https://docs.elfsquad.io/apis/quotation

5. Adding the configuration to the quotation​

In order to complete this step you need the id of the configuration that was created in step 2. You will also need the id of the quotation that was created in the previous step. To add the configuration to the quotation the following request must be sent:

PUT: https://api.elfsquad.io/configurator/3/configurator/addtoquotation

For this request a JSON body with the following format is required:

{
  "quotationId": "1ceb365d-7c0e-435f-8012-dd887707710b",
  "configurationIds": ["747fe28d-fd35-4938-aac2-7a102b20196e"]
}

The value of quotationId should be replaced by the id of the quotation from the previous step. The value of configurationIds should be an array containing the id of the configuration from step 2. Please note that adding multiple (unique) configurations in one request is supported. After the request completes, the configuration will be added to the quotation. The new quotation is immediately visable in the EMS. Want to change the status of your newly created quotation? Please refer to our documentation: https://support.elfsquad.io/hc/en-us/articles/9435941123484-Quotation-functions-in-API.

In this tutorial, I will provide a quick overview of how to implement your customer-facing showroom in Angular.

You can find the resulting project in the showroom-example repository on our Github.

ℹ️ If you’re not familiar with Angular, you can follow the Angular getting started guide.

Setting up a new Angular project​

Create a new Angular project using the Angular CLI.

Creating the project​

    ng new ShowroomExample --routing=true --style=css

Once that’s finished, you should be able to run the application and open it on localhost:4200.

    ng serve

Installing dependencies​

For this tutorial, we’ll make use of the @elfsquad/authentication and @elfsquad/configurator packages.

These are developed and maintained by Elfsquad.

    npm install @elfsquad/authentication
    npm install @elfsquad/configurator

Adding some basic html/css​

In the index.html, we add a little bit of styling:

    <style>
        * {
          font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
        }

        body, p {
          margin: 0;
          padding: 0;
        }
    </style>

And in the app.component.html file, we’ll remove everything but the <router-outlet></router-outlet> tag.

Creating the configurator context​

We communicate with the Elfsquad API through the ConfiguratorContext. We can initialize this class in the app.module.ts file. The configurator context can be used for both anonymous and showrooms that require a logged in user.

    import { NgModule } from '@angular/core';
    import { BrowserModule } from '@angular/platform-browser';
    import {ConfiguratorContext, IConfiguratorOptions} from '@elfsquad/configurator';
    import {AuthenticationMethod} from '@elfsquad/configurator/dist/configurator/IConfiguratorOptions';

    import { AppRoutingModule } from './app-routing.module';
    import { AppComponent } from './app.component';
    import { ProductOverviewComponent } from './product-overview/product-overview.component';
    import { FormsModule } from '@angular/forms';

    const options: IConfiguratorOptions = {
      authenticationMethod: AuthenticationMethod.ANONYMOUS,
      tenantId: '5dcd73c7-c0e9-44e8-85f3-dfef7553e8a2',
    };

    const configuratorContext = new ConfiguratorContext(options);

    @NgModule({
      declarations: [
        AppComponent,
        ProductOverviewComponent
      ],
      imports: [
        BrowserModule,
        AppRoutingModule,
        FormsModule
      ],
      providers: [
        { provide: ConfiguratorContext, useValue: configuratorContext }
      ],
      bootstrap: [AppComponent],
    })
    export class AppModule { }

If you want to require a logged in user, you can need to change a few snippets of code in the example above.

1. Add the authenticationOptions to the configuratorOptions object:

    const options = {
      tenantId: '5dcd73c7-c0e9-44e8-85f3-dfef7553e8a2',
      authenticationMethod: AuthenticationMethod.USER_LOGIN,
      authenticationOptions: {
        clientId: '60a98ec8-c9f7-4b4e-a809-0492f25b8037',
        redirectUri: 'http://localhost:4200',
      }
    };

1. Check if the user is logged in and if not, redirect to the login page.

    const configuratorContext = new ConfiguratorContext(options);
    configuratorContext.authenticationContext.isSignedIn().then(signedIn => {
      if (signedIn) {
        return;
      }
      configuratorContext.authenticationContext.signIn();
    });

⚠️ Make sure to replace the tenantId with your tenant id

Creating the product overview page​

We start by creating a ProductOverview component. This component will show all configuration models available.

ng generate component ProductOverview

Adding the product overview route​

Now that we’ve created the component, we should register it as a route, so our users can access it. You can register the route by adding it to the app-routing-module.ts file.

    import { NgModule } from '@angular/core';
    import { RouterModule, Routes } from '@angular/router';
    import {ProductOverviewComponent} from './product-overview/product-overview.component';

    const routes: Routes = [
      { path: '', component: ProductOverviewComponent },
    ];

    @NgModule({
      imports: [RouterModule.forRoot(routes)],
      exports: [RouterModule]
    })
    export class AppRoutingModule { }

Retrieving the configuration models​

The first step to creating the product overview is retrieving a list of available configuration models. We can do this in the ngOnInit method of the ProductOverview component.

    import { Component, Inject, OnInit } from '@angular/core';
    import { ConfigurationModel, ConfiguratorContext } from '@elfsquad/configurator';

    @Component({
      selector: 'app-product-overview',
      templateUrl: './product-overview.component.html',
      styleUrls: ['./product-overview.component.css']
    })
    export class ProductOverviewComponent implements OnInit {
      public configurationModels: ConfigurationModel[] = [];

      constructor(
        @Inject(ConfiguratorContext) private configuratorContext: ConfiguratorContext,
      ) { }

      ngOnInit(): void {
        this.configuratorContext.getConfigurationModels().then(configurationModels => {
          this.configurationModels = configurationModels.features;
        });
      }
    }

The configuration models should now be retrieved when you open the page.

Displaying the configuration models​

To display those models, we create a grid overview in the product-overview.component.html file.

    <div class="product-overview">
      <div *ngFor="let model of configurationModels" class="product-card" [routerLink]="['configure', model.featureModelId]">
        <img [src]="model.imageUrl" />
        <h3 [innerHTML]="model.description"></h3>
      </div>
    </div>

And the following CSS:

    div.product-overview {
      padding: 80px;
      display: flex;
      gap: 40px;
      flex-wrap: wrap;
      justify-content: center;
    }

    div.product-overview > div.product-card {
      padding: 8px;
      width: 28%;
      box-shadow: rgba(99, 99, 99, 0.2) 0px 2px 8px 0px;
    }

    div.product-overview > div.product-card > img {
      height: auto;
      width: 100%;
    }

Creating the configurator page​

Now that we have a product overview page, we can proceed to build the actual configurator. This is the page on which users can configure their model.

Let’s start by creating a ConfiguratorComponent

    ng generate component Configurator

And registering a route to access the configurator page. Notice we use a :id parameter in the path. This id can either be the name or the id of a configuration model.

    { path: 'configure/:id', component: ConfiguratorComponent }

Starting a new configuration​

Once the user visits the configurator page, we need to start a new configuration. To do this, we’ll:

1. Inject the ActivatedRoute, from which we can retrieve the configuration model id

2. Use the ConfiguratorContext to start a new configuration

3. Store the new configuration on the ConfiguratorComponent

4. Update ConfiguratorComponent.configuration every time the configuration is updated.

    import { Component, OnInit } from '@angular/core';
    import { ActivatedRoute } from '@angular/router';
    import { Configuration, ConfiguratorContext } from '@elfsquad/configurator';

    @Component({
      selector: 'app-configurator',
      templateUrl: './configurator.component.html',
      styleUrls: ['./configurator.component.css']
    })
    export class ConfiguratorComponent implements OnInit {
      public configuration: Configuration | undefined;

      constructor(
        private route: ActivatedRoute,
        private configuratorContext: ConfiguratorContext
      ) { }

      ngOnInit(): void {
        this.route.params.subscribe(params => {
          this.configuratorContext.newConfiguration(params['id'])
            .then(configuration => {
              this.configuration = configuration;
            });
          this.configuratorContext.onUpdate((e: CustomEvent) => {
            this.configuration = e.detail;
          });
        });
      }
    }

The resulting configuration object contains many different fields, all of which can be explored on docs.elfsquad.io.

This tutorial will focus mainly on steps and displaying the price.

The configuration object has a steps property, which contains an array of all steps. A step contains features, and each feature can contain child features.

• Title
• Features
  • Description
  • UnitPrice
  • TotalPrice
  • Type
  • Features (Children of the current feature, recursive)
    • ...
  • ...

Displaying the steps​

We will display only one step at a time. To do this, we’ll add a activeIndex and functions to go the next/previous step to the configurator.component.ts file.

      public activeIndex: number = 0;

      public next() {
        this.activeIndex += 1;
      }

      public previous() {
        this.activeIndex -= 1;
      }

In the HTML, we’ll iterate overall features in the step and display them by using the app-feature tag. This is a component we’ll create in the next step.

    <div *ngFor="let step of configuration?.steps ?? []; let i = index">
      <div class="step" [class.active]="i === activeIndex">
        <app-feature [configuration]="configuration" [feature]="feature" *ngFor="let feature of step.features"></app-feature>
      </div>
    </div>

    <div class="footer">
      <span>
        <b>Total price:</b>
        {{ configuration?.totalPrice | currency: 'EUR': true }}
      </span>
      <br />
      <button
        [disabled]="activeIndex === 0"
        (click)="previous()"
      >
        Previous
      </button>
      <button
        [disabled]="activeIndex === (configuration?.steps ?? []).length - 1"
        (click)="next()"
      >
        Next
      </button>
    </div>

and CSS

    div.step {
      display: none;
      max-width: 400px;
    }

    div.step.active {
      display: block;
    }

    div.footer {
      margin-top: 12px;
      margin-left: 24px;
    }

Creating the feature component​

We show features using the app-feature tag in the previous step. This is a new component that we’re about to implement.

Because of the recursive nature of features, we need to create a new component for them.

    ng generate component Feature

This component will take a feature as input.

    import { Component, Input, OnInit } from '@angular/core';
    import { ConfigurationFeature, Configuration } from '@elfsquad/configurator';

    @Component({
      selector: 'app-feature',
      templateUrl: './feature.component.html',
      styleUrls: ['./feature.component.css']
    })
    export class FeatureComponent implements OnInit {
      @Input('feature') feature: ConfigurationFeature | undefined;
      @Input('configuration') configuration: Configuration | undefined;

      constructor( ) { }

      ngOnInit(): void { }
    }

Toggling features on/off​

For this example, we’ll only enable toggling features on and off, so we’ll only have to implement the toggle() function.

This function will (de)select an option within the configuration model.

      toggle(): void {
        if (!this.feature)
          return;

        if (!this.configuration)
          return;

        const value = this.feature.isSelected ? 0 : 1;
        this.configuration.updateRequirement(
          this.feature.id,
          this.feature.isSelected,
          value
        );
      }

Displaying the feature​

For displaying features, we’ll add some HTML to the feature.component.html file.

    <div class="feature">
      <div class="header">
        <span [innerHTML]="feature?.description"></span>
        <input
         type="checkbox"
         [checked]="feature?.isSelected"
         (click)="toggle()"
         *ngIf="feature?.type === 0"
        />
        <input
         type="radio"
         [checked]="feature?.isSelected"
         (click)="toggle()"
         *ngIf="feature?.type === 2"
        />
      </div>
      <span *ngIf="feature?.minValue == feature?.maxValue && feature?.value != 0 && feature?.value != 1">
        {{feature?.value}} {{feature?.unitOfMeasurement}}
      </span>
      <span>{{feature?.unitPrice}}</span>
      <app-feature
        [configuration]="configuration"
        [feature]="f"
        *ngFor="let f of feature?.features"
        ></app-feature>
    </div>

And add the css below to feature.component.css

    div.feature {
      width: 100%;
      height: 100%;
      margin-left: 24px;
      margin-bottom: 6px;
    }

    div.feature > div.header {
      display: flex;
      align-items: center;
      justify-content: space-between;
    }

Requesting a quote​

Now that we are able to configure a product, we can go ahead and request a quotation. We’ll add a button to the configurator page:

    <button [routerLink]="['/checkout', configuration?.id]">Request quote</button>

Creating the checkout page​

As before, we’ll start by creating the Checkout component.

    ng generate component Checkout

and add the route to the app-routing.module.ts file. In this route, the id stands for the configuration id.

      { path: 'checkout/:id', component: CheckoutComponent }

In the checkout.component.ts file, we’ll create a function to request a quote

     import { Component, OnInit } from '@angular/core';
import { ConfiguratorContext, QuotationRequest } from '@elfsquad/configurator';

@Component({
  selector: 'app-checkout',
  templateUrl: './checkout.component.html',
  styleUrls: ['./checkout.component.css']
})
export class CheckoutComponent implements OnInit {

  constructor(private configuratorContext : ConfiguratorContext) { }

  ngOnInit(): void {
  }
  public isSubmitted = false;
  public model: QuotationRequest = {};

  requestQuote() {
    this.configuratorContext.requestQuote(this.model).then(_ => {
      this.isSubmitted = true;
    });
  }
}

The checkout page itself, is divided into two sections. One before the request is submitted, and one afterward:

    <h3>Request quote</h3>

    <div *ngIf="!isSubmitted">
      <form>
        <fieldset>
          <legend>Contact information</legend>
          <label>
            First name:
            <input [(ngModel)]="model.firstName" name="firstName" />
          </label>
          <label>
            Last name:
            <input [(ngModel)]="model.lastName" name="lastName" />
          </label>
          <label>
            Email:
            <input [(ngModel)]="model.email" name="email" />
          </label>
          <label>
            Phone:
            <input [(ngModel)]="model.phoneNumber" name="phone" />
          </label>
          <legend>Company information</legend>
          <label>
            Company name:
            <input [(ngModel)]="model.companyName" name="companyName" />
          </label>
          <label>
            Street:
            <input [(ngModel)]="model.streetName" name="streetName" />
          </label>
          <label>
            City:
            <input [(ngModel)]="model.city" name="city" />
          </label>
          <label>
            Postal code:
            <input [(ngModel)]="model.postalCode" name="state" />
          </label>
          <input type="submit" value="Submit" (click)="requestQuote()" />
        </fieldset>
      </form>
    </div>

    <div *ngIf="isSubmitted">
      <h3>Thank you for your request!</h3>
      <p>We will contact you shortly.</p>
    </div>

Quick overview​

In this tutorial I will provide a quick overview of the endpoints that can be used to implement your own customer-facing configurator.

Step 1. Retrieve a list of configuration models.​

The first thing we want to do is provide the user with a selection of available configuration models. In order to achieve this we can use the configuration models endpoint

GET /configurator/1/configurator/configurationmodels

Step 2. Start a new configuration​

When a user has selected a configuration model to be configured, we can use the featureModelId property to start a new configuration session. We use the start configuration endpoint for this.

GET /configurator/1/configurator/new/{featureModelId}

Result (Some data has been emitted for clarity.):

{
  "id": "9c83b007-7e61-4b4c-9920-f125606844d5",
  "currencyIso": "eur",
  "currency": {
    "iso": "eur",
    "name": "Euro",
    "symbol": "\u20ac",
    "decimalDigits": 2,
    "rounding": 0,
    "namePlural": "Euros",
    "isDefault": false
  },
  "languageIso": "nl",
  "countryIso": "nl",
  "featureModelId": "b8230fc6-454c-4190-a33a-08d5640714ca",
  "featureModel": ..., 
  "values": {
    "7bcf2363-4300-4a6a-faa9-08d5640714d2": 1,
    "580b4519-1a7a-46f9-fa7d-08d5640714d2": 4,
    "8c81fabc-eaed-41e2-8ec2-08d5d10145ad": 4,
    "e22f606d-3e4e-462e-8ec3-08d5d10145ad": 72,
    ...
  },
  "conflicts": null,
  "basePrice": 42750,
  "basePriceLabel": "\u20ac 42.750,00",
  "basePriceIncVAT": 42750,
  "basePriceIncVATLabel": "\u20ac 42.750,00",
  "basePriceExVAT": 42750,
  "basePriceExVATLabel": "\u20ac 42.750,00",
  "additionalPrice": 10730,
  "additionalPriceLabel": "\u20ac 10.730,00",
  "additionalPriceIncVAT": 10730,
  "additionalPriceIncVATLabel": "\u20ac 10.730,00",
  "additionalPriceExVAT": 10730,
  "additionalPriceExVATLabel": "\u20ac 10.730,00",
  "totalPrice": 53480,
  "totalPriceLabel": "\u20ac 53.480,00",
  "totalPriceExVAT": 53480,
  "totalPriceExVATLabel": "\u20ac 53.480,00",
  "totalPriceIncVAT": 53480,
  "totalPriceIncVATLabel": "\u20ac 53.480,00",
  "leasePrices": null,
  "leasePricesLabels": null
}

Overview of important configuration properties:

Step 3. Update value​

In order to update a value for a particular option we use the update requirement endpoint

PUT /configurator/1/configurator/{configurationId}?ignoreConflicts=true

• The ignoreConflicts parameter is optional. When this parameter is set to true the configurator will automatically resolve any conflicts that might occur.

Request body:

{featureModelNodeId: "949af91c-8a0b-4540-fa87-08d5640714d2", value: 1}