Add Pricefx connector documentation #608
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,115 @@ | ||
| --- | ||
| title: Example | ||
| --- | ||
|
|
||
| # Example | ||
|
|
||
| ## What you'll build | ||
|
|
||
| This example builds an automation that connects to Pricefx and lists the price list types defined in your partition. The automation calls the **List Price List Types** operation and logs the result. | ||
|
|
||
| **Operations used:** | ||
| - **List Price List Types** : Retrieves the price list types configured for your partition. | ||
|
|
||
| ## Architecture | ||
|
|
||
| ```mermaid | ||
| flowchart LR | ||
| A((User)) --> B[List Price List Types] | ||
| B --> C[Pricefx Connector] | ||
| C --> D[(Pricefx)] | ||
| ``` | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - A Pricefx username, password, and partition. See the connector's [Setup Guide](setup-guide.md). | ||
|
|
||
| ## Setting up the Pricefx integration | ||
|
|
||
| > **New to WSO2 Integrator?** Follow the [Create a New Integration](../../../../develop/create-integrations/create-a-new-integration.md) guide to set up your integration first, then return here to add the connector. | ||
|
|
||
| ## Adding the Pricefx connector | ||
|
|
||
| ### Step 1: Open the connector palette | ||
|
|
||
| Select **Add Connection** in the **Connections** section. | ||
|
|
||
|  | ||
|
|
||
| ### Step 2: Select the Pricefx connector | ||
|
|
||
| Enter "pricefx" in the search box to filter the connector list, then select the **Pricefx** connector card (`ballerinax/pricefx`) to open its connection configuration form. | ||
|
|
||
| ## Configuring the Pricefx connection | ||
|
|
||
| ### Step 3: Bind the connection parameters to configurable variables | ||
|
|
||
| Bind the required connection fields to configurable variables. | ||
|
|
||
| - **Config** : The authentication method to use. Select **BasicCredentials** and bind its `username`, `password`, and `partition` fields. | ||
|
|
||
|  | ||
|
|
||
| ### Step 4: Save the connection | ||
|
|
||
| Select **Save Connection** and verify that the connection appears in the **Connections** section. | ||
|
|
||
|  | ||
|
|
||
| ### Step 5: Set actual values for your configurables | ||
|
|
||
| 1. Select **Configurations** at the bottom of the project tree under **Data Mappers**. | ||
| 2. Enter a value for each configurable listed below before you run the integration. | ||
|
|
||
| - **username** (`string`) : Your Pricefx username. | ||
| - **password** (`string`) : Your Pricefx password. | ||
| - **partition** (`string`) : Your Pricefx partition name. | ||
|
|
||
| ## Configuring the Pricefx List Price List Types operation | ||
|
|
||
| ### Step 6: Add an automation entry point | ||
|
|
||
| 1. In the left panel under **Entry Points**, select **+** (**Add Entry Point**). | ||
| 2. Under **Automation**, select **Automation**. | ||
| 3. In the **Create New Automation** dialog, accept the default settings and select **Create**. | ||
|
|
||
| The canvas switches to the Automation flow view, showing a Start node, an Error Handler node, and an End node. | ||
|
|
||
| ### Step 7: Select the List Price List Types operation | ||
|
|
||
| 1. In the automation flow body on the canvas, select the **+** (Add Step) button between the Start and Error Handler nodes to open the step-addition panel. | ||
| 2. Under **Connections** in the step panel, select the **pricefxClient** connection node to expand it and reveal all available Pricefx API operations. | ||
|
|
||
|  | ||
|
|
||
| 3. Select **List Price List Types** from the list. This operation has no required parameters, so only the result variable needs a name. | ||
|
|
||
| - **Result** : The name of the variable that holds the returned price list types. | ||
|
|
||
|  | ||
|
|
||
| 4. Select **Save** to add the Pricefx operation step to the automation flow. | ||
|
|
||
| ### Step 8: Log the List Price List Types result | ||
|
|
||
| Add a log action for the returned value, then return to the visual flow. | ||
|
|
||
|  | ||
|
|
||
| ## Try it yourself | ||
|
|
||
| Try this sample in WSO2 Integration Platform. | ||
|
|
||
| [](https://console.devant.dev/new?gh=wso2/integration-samples/tree/main/integrator-default-profile/connectors/pricefx_connector_sample) | ||
|
|
||
| [View source on GitHub](https://github.com/wso2/integration-samples/tree/main/integrator-default-profile/connectors/pricefx_connector_sample) | ||
|
|
||
| ## More code examples | ||
|
|
||
| The `Pricefx` connector offers practical examples illustrating its use in various scenarios. | ||
| Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-pricefx/tree/main/examples/), covering the following use cases: | ||
|
|
||
| 1. [Product catalog management](https://github.com/ballerina-platform/module-ballerinax-pricefx/tree/main/examples/product-catalog-management): Add a new product to the catalog, update one of its fields, then list matching products to confirm the change. | ||
| 2. [Customer quote workflow](https://github.com/ballerina-platform/module-ballerinax-pricefx/tree/main/examples/customer-quote-workflow): Add a new customer, create a quote for them, then submit the quote for approval. | ||
| 3. [Price list calculation](https://github.com/ballerina-platform/module-ballerinax-pricefx/tree/main/examples/price-list-calculation): Create a new price list, run its calculation, then fetch the calculated price list. | ||
| 4. [Attachment upload workflow](https://github.com/ballerina-platform/module-ballerinax-pricefx/tree/main/examples/attachment-upload-workflow): Create an upload slot for a customer record, upload a file to it, then list the customer's files. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| --- | ||
| connector: true | ||
| connector_name: "pricefx" | ||
| title: "Pricefx" | ||
| description: "Overview of the ballerinax/pricefx connector for WSO2 Integrator." | ||
| --- | ||
|
|
||
| [Pricefx](https://www.pricefx.com/) is a cloud-native pricing and revenue management platform that helps enterprises manage price lists, calculation grids, quotes, contracts, and rebate agreements across their sales organization. The `ballerinax/pricefx` connector provides a client for the [Pricefx Backend API](https://api.pricefx.com/), covering master data (products, customers, sellers), pricing (price lists, manual price lists, calculation grids, condition records), sales (quotes, contracts, rebate agreements, sales compensations), and platform administration (users, workflow, data manager, notifications, comments, custom forms, and more). | ||
|
|
||
| ## Key Features | ||
|
Contributor
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Use sentence case for the H2 heading. Change As per path instructions, non-H1 headings must use sentence case. 🤖 Prompt for AI AgentsSource: Path instructions |
||
|
|
||
| - Manage products, customers, sellers, and their extension fields | ||
| - Create, calculate, and manage price lists, manual price lists, and calculation grids | ||
| - Build quotes, submit and revoke them, and convert them to deals | ||
| - Manage contracts (agreements and promotions) and rebate agreements | ||
| - Run rebate calculations and manage rebate record groups | ||
| - Handle sales compensation plans and records | ||
| - Upload, download, and manage attachments and files | ||
| - Manage users, business roles, and workflow delegations | ||
| - Work with the Data Manager, lookup tables, and key-value stores | ||
| - Authenticate with username/password, an API key, OAuth 2.0, or a pre-signed external JWT | ||
| - Transparent re-authentication - the client automatically refreshes a short-lived token and retries once whenever a request comes back unauthenticated | ||
|
|
||
| ## Actions | ||
|
|
||
| The connector exposes a single client for interacting with the Pricefx API. | ||
|
|
||
| | Client | Actions | | ||
| |---|---| | ||
| | [`Client`](action-reference.md#client) | Manages Pricefx products, customers, sellers, condition records, price lists, manual price lists, calculation grids, quotes, contracts, rebate agreements and calculations, sales compensations, attachments, users, workflow, data manager, and authentication. | | ||
|
|
||
| ## Documentation | ||
|
|
||
| - [Setup Guide](setup-guide.md) - Get Pricefx credentials | ||
| - [Actions](action-reference.md) - Available operations | ||
|
|
||
| ## How to contribute | ||
|
|
||
| Contribute to the connector's development on GitHub: [module-ballerinax-pricefx](https://github.com/ballerina-platform/module-ballerinax-pricefx). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,97 @@ | ||
| --- | ||
| connector: true | ||
| connector_name: "pricefx" | ||
| title: "Setup Guide" | ||
| description: "How to set up and configure the ballerinax/pricefx connector." | ||
| --- | ||
|
|
||
| # Setup Guide | ||
|
|
||
| This guide walks you through getting the details the connector needs to authenticate and communicate with your Pricefx partition. | ||
|
|
||
| ## Choose an authentication method | ||
|
|
||
| The connector supports several ways to authenticate with Pricefx. Provide exactly one of the following credential combinations. | ||
|
|
||
| ### 1. Basic Authentication | ||
|
coderabbitai[bot] marked this conversation as resolved.
|
||
|
|
||
| The most common setup, and the one to reach for first. | ||
|
|
||
| Your user name, password, and partition are provisioned when your Pricefx account is created - ask your Pricefx administrator if you don't already have them. The partition name also appears in your instance's login URL, in the form `https://<your-node>.pricefx.com/pricefx/<your-partition>`. | ||
|
|
||
| You only pay for a Basic authenticated request once: the connector uses your username, password, and partition to bootstrap a session token when the client is created, then reuses that token for every request afterward instead of sending your credentials again. | ||
|
|
||
| ### 2. JWT Token Authentication | ||
|
|
||
| Provide `jwt` on its own - no username, password, or partition needed. | ||
|
|
||
| If you already have a non-expiring Pricefx JWT, you can use it directly by setting it as `jwt`. | ||
|
|
||
| ### 3. OAuth 2.0 Authentication | ||
|
|
||
| Provide `clientId`, `refreshToken`, and optionally `clientSecret`. | ||
|
|
||
| #### Registering an OAuth client | ||
|
|
||
| On the Pricefx side, go to **Administration > Configuration > System Configuration > Advanced Configuration Options** and add a per-partition configuration named `oauthConfiguration` with a value shaped like this: | ||
|
|
||
| ```json | ||
| { | ||
| "knownClients": { | ||
| "<yourClientName>": { | ||
| "redirect_uri": "<the redirect URI your integration listens on>", | ||
| "client_secret": "<a secret of your choosing>", | ||
| "client_description": "A short label shown on the consent screen" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| - The key you choose under `knownClients` (`<yourClientName>` above) is the value you set as `clientId`. | ||
| - `client_secret`, if you set one, is the value you set as `clientSecret`. | ||
| - `redirect_uri` must match wherever your integration is set up to receive the sign-in redirect. | ||
|
|
||
| #### Getting a refresh token | ||
|
|
||
| `refreshToken` comes from signing in once through Pricefx's OAuth 2.0 consent screen for the client you just registered, and approving access. That sign-in step is interactive (it happens in a browser) and can't be automated by this connector, but it's a one-time setup step - the consent screen hands back a refresh token as part of the exchange, and that's the value you configure here. | ||
|
|
||
| Once you have a refresh token, the connector fetches and refreshes access tokens automatically - you never need to repeat that step. | ||
|
|
||
| ### 4. External JWT Authentication | ||
|
|
||
| You can use a third-party JSON Web Token for authentication (for example, with Salesforce as the signer). As with SAML, no hard-coded per-user credentials are needed - instead, a system-to-system trust relationship is established using signed tokens. | ||
|
|
||
| #### Configuring the trust relationship | ||
|
|
||
| On the Pricefx side, go to **Administration > Configuration > System Configuration > Advanced Configuration Options** and add a per-partition configuration named `externalJWTConfiguration` with a value shaped like this: | ||
|
|
||
| ```json | ||
| { | ||
| "entries": { | ||
| "<externalSystemName>": { | ||
| "publicKey": "<public key used by the external system for signing, in PEM format>", | ||
| "permissions": "<null, or a JSON list of permission-name strings>" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| - **`externalSystemName`** - a JSON-safe name for the external system (letters, digits only - no whitespace). This is the same name you pass as `systemName` to the connector. You can register as many external systems as you like, each under its own name. | ||
| - **`publicKey`** - the external system's public key, as a PEM-formatted string. Pricefx only supports RSA keys. | ||
| - **`permissions`** - leave `null` (or omit it) to not further restrict permissions beyond what the authenticated user already has. If you provide a list of permission-name strings instead, a token issued under this configuration can only call endpoints whose required permission is in that list. | ||
|
|
||
| :::caution | ||
| The `permissions` list is only an additional filter, on top of the authenticated user's own permissions - it can't grant a user something they couldn't otherwise do. Use it to restrict a given trust relationship to a narrower set of API calls than the user would normally have access to. | ||
| ::: | ||
|
|
||
| Once the trust relationship is configured, give the connector two values: `systemName`, set to the name you registered above, and `jwt`, set to a JWT signed by that external system. | ||
|
|
||
| The connector automatically re-authenticates and retries once whenever a request comes back unauthenticated, so a long-lived client instance keeps working without manual re-initialization. | ||
|
|
||
| ## Note your service URL | ||
|
|
||
| The connector connects to `https://<your-node>.pricefx.com/pricefx/<your-partition>` by default. Confirm your node and partition name with your Pricefx administrator if you're not sure. | ||
|
|
||
| ## Next steps | ||
|
|
||
| - [Actions](action-reference.md) - Available operations | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.