Edit a transaction process with Sharetribe CLI

In this guide, we will extend the marketplace review period with the Sharetribe CLI. After we’ve made the change, we’ll push the updated transaction process version and update the existing alias.

If you want to create a new transaction process based on an existing one instead, you can follow these instructions to create a new transaction process and alias:

• Create a new transaction process with the Sharetribe CLI

Let’s get started!

Pull the existing process

The first thing to do is to list all the existing processes with CLI command process list.

Remember to include your marketplace ident to the command with the --marketplace <marketplace ident here> options or the short version -m <your marketplace ident here>:

flex-cli process list -m my-marketplace-dev

From the list of processes, pick the one that you want to edit. In this guide, we’ll use process default-booking, version 1. You might have different processes in your marketplace, so you can use those. However, you can check the content of this default booking example process online from Sharetribe example processes  Github repository.

We can pull the process with the process pull command. Let’s see the options that the command needs:

flex-cli help process pull

We can see that required options are:

• --path the path where the process is saved
• --process name of the process
• --version or --alias. Process version or alias pointing to the version that we want to pull
• --marketplace the marketplace

Pull the process and save it to process directory:

flex-cli process pull --process default-booking --version 1 --path process -m my-marketplace-dev

See what’s inside the process directory:

ls process

(Windows users: use dir instead of ls)

You can see that there are two items in the directory:

• process.edn file, which defines the transaction process
• templates directory, which contains all the transaction email templates for this process

Next, we’re going to edit the process description.

Extend the review period

Open the process.edn in your favorite editor.

(To get proper syntax highlighting, you may need to install a plugin to your editor. edn is subset of Clojure, so a Clojure plugin will give you proper edn highlighting.)

From the process.edn file, you’ll find a map with a key :transitions. The value of the :transitions key is a vector of transition in your marketplace. Each transition contains values for keys like :name, :actor, :actions, :to and :from.

To extend the review period in the transaction process, we need to find the transition where the review periods are defined. In the Sharetribe default processes, the review period length is defined in the transition :transition/expire-review-period, and if one participant has already reviewed the other, in either :transition/expire-provider-review-period or :transition/expire-customer-review-period. By default, the review periods are defined as 7 days.

When you have found the transitions, change the value of the :fn/period in the :at time expression to ["P10D"] to extend the review period to 10 days.

 {:format :v3
  :transitions
  [{:name :transition/inquire,
    ;;...
  {:name :transition/expire-review-period,
   :at
   {:fn/plus
-    [{:fn/timepoint [:time/booking-end]} {:fn/period ["P7D"]}]},
+    [{:fn/timepoint [:time/booking-end]} {:fn/period ["P10D"]}]},
   :actions [],
   :from :state/delivered,
   :to :state/reviewed}
  {:name :transition/expire-provider-review-period,
   :at
   {:fn/plus
-    [{:fn/timepoint [:time/booking-end]} {:fn/period ["P7D"]}]},
+    [{:fn/timepoint [:time/booking-end]} {:fn/period ["P10D"]}]},
   :actions [{:name :action/publish-reviews}],
   :from :state/reviewed-by-customer,
   :to :state/reviewed}
  {:name :transition/expire-customer-review-period,
   :at
   {:fn/plus
-    [{:fn/timepoint [:time/booking-end]} {:fn/period ["P7D"]}]},
+    [{:fn/timepoint [:time/booking-end]} {:fn/period ["P10D"]}]},
   :actions [{:name :action/publish-reviews}],
   :from :state/reviewed-by-provider,
   :to :state/reviewed}

Save the changes you’ve made to process.edn file.

Validate and push the process

After each modification to the process.edn file, it’s good idea to validate that the changes are correct. The CLI command process can do this:

flex-cli process --path process

In case the process.edn file is valid, you’ll see a description of your process with all the states, transitions and notifications listed. In case the file is invalid, you’ll see a validation error.

Now that we have validated the process.edn file we are ready to push the changes to Sharetribe:

flex-cli process push --path process --process default-booking -m my-marketplace-dev

After the process is successfully pushed, you’ll see a new process version in Console .

Please note that pushing the changes to Sharetribe doesn’t immediately change the way how your marketplace works. The existing transactions are still using the old process version and the new transaction will be using the old process as long as the existing alias is pointing to it.

So, to take the changes into use, let’s update the alias!

Update alias

First, let’s see what aliases are pointing to which versions. We can do this by using the process list command with the --process option:

flex-cli process list --process default-booking -m my-marketplace-dev

You’ll see a list of process versions and aliases pointing to them. The alias always consists of two parts where the first part is the process name and the second part is the alias name.

You’ll also see that the newly created version doesn’t have an alias pointing to it. Let’s change that.

In the default process, the name of the existing alias is release-1. The command to update the alias is process update-alias:

flex-cli process update-alias --process default-booking --alias release-1 --version 2 -m my-marketplace-dev

This command updates the alias release-1 to point to default-booking process version 2.

To verify that the change was successful, you can rerun the process list command and see that the release-1 alias is now pointing to the version 2.

Be careful when updating aliases! Updating the alias will take the process changes in use immediately. In case you make changes where you add/remove/rename states or transitions, updating alias may potentially break your marketplace front-end if you haven’t updated it to work with the new process.

The review period has now been changed! Next time you initiate a new transaction with the alias default-booking/release-1 the review period is 10 days.

Summary

In this tutorial we pulled an existing process definition with the Sharetribe CLI. We extended the review period to 10 days, validated the process file and pushed it back to Sharetribe. Finally, we updated the alias to point to the new version.

You know now how to make simple modifications to the process. Have a look at the transaction process format reference and the transaction process actions reference to read about all the possibilities that transaction process engine gives to you.

When you modify the transitions or states in your transaction process when editing your process, you will need to update your client application accordingly. If you are using the Sharetribe Web Template, you can follow these instructions to reflect your changes in the client:

• Change transaction process in Sharetribe Web Template

You may also want to edit the transaction email templates. You can follow these instructions to modify your email templates:

• Editing email templates with Sharetribe CLI