From 87256e81b3684fe766ca59f2bb57532ddf6297e9 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 22 Dec 2022 17:13:20 +0200 Subject: [PATCH] docs: added an upgrade guide for v1.7.1 (#2868) * docs: added an upgrade guide for 1.7.1 * docs: added more required changes for the release * docs: removed link to payment provider docs * docs: reordered upgrade guides in desc order * added export to code snippet * added details about update_request property * fixed the text * added link to scheduled jobs docs --- .../advanced/backend/upgrade-guides/1-7-1.md | 115 ++++++++++++++++++ www/docs/sidebars.js | 27 ++-- 2 files changed, 131 insertions(+), 11 deletions(-) create mode 100644 docs/content/advanced/backend/upgrade-guides/1-7-1.md diff --git a/docs/content/advanced/backend/upgrade-guides/1-7-1.md b/docs/content/advanced/backend/upgrade-guides/1-7-1.md new file mode 100644 index 0000000000..86588ab717 --- /dev/null +++ b/docs/content/advanced/backend/upgrade-guides/1-7-1.md @@ -0,0 +1,115 @@ +--- +description: 'Actions Required for v.1.7.1' +--- + +# v1.7.1 + +Version `1.7.1` of Medusa introduces the `JobSchedulerService` which changes how scheduled/cron jobs are created. + +## Overview + +Version `1.7.1` of Medusa introduces a new service `JobSchedulerService` that handles all logic and functionality related to created scheduled (previously named cron jobs). + +With this introduction, the previous use of `EventBus` to create a cron job has been deprecated of using the `JobSchedulerService`. + +In addition, this version features some fixes to gift cards that requires running migrations, and changes to how payment providers are implemented. + +## Actions Required + +### Run Migrations + +In the directory of your Medusa server, run the following command after updating the server: + +```bash +medusa migrations run +``` + +### Run Migration Script + +Following the fix gift cards calculation, you also need to run a migration script after updating the server. + +Start by adding the following environment variables in `.env`: + +```bash +TYPEORM_CONNECTION=postgres +TYPEORM_URL= +TYPEORM_USERNAME= +TYPEORM_PASSWORD= +TYPEORM_DATABASE= +TYPEORM_ENTITIES=./node_modules/@medusajs/medusa/dist/models/*.js +TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js +``` + +Make sure to replace ``, ``, ``, and `` with your database connection details. + +Then, run the following command in the root directory of your Medusa server: + +```bash +node ./node_modules/@medusajs/medusa/dist/scripts/gift-card-tax-rate-migration.js +``` + +### Change to JobSchedulerService + +In your loader file that creates a cron job, replace the use of `eventBus` to `jobSchedulerService`: + +```ts +const myJob = async (container, options) => { + const jobSchedulerService = container.resolve("jobSchedulerService"); + jobSchedulerService.create("my-job", {}, "0 0 * * *", async () => { + //... + }); +} + +export default myJob; +``` + +You can learn more in the [How to Create a Scheduled Job](../scheduled-jobs/create.md) documentation. + +### Change to Payment Provider + +This version of Medusa introduces a change in how payment providers are implemented. Mainly, the signature of the `createPayment` and `updatePayment` methods have changed, and the old signature is now deprecated. + +Although this change is currently backwards compatible, it is recommended to change the signature of these methods to the following: + +```ts +import { PaymentContext, PaymentSessionResponse } from '@medusajs/medusa' + +async createPayment(context: PaymentContext): Promise { + //... +} + +async updatePayment(paymentSessionData: PaymentSessionData, context: PaymentContext): Promise { + //... +} +``` + +Where `context` in both `createPayment` and `updatePayment` is made up of the following properties: + +```ts +type PaymentContext = { + cart: { + context: Record + id: string + email: string + shipping_address: Address | null + shipping_methods: ShippingMethod[] + } + currency_code: string + amount: number + resource_id?: string + customer?: Customer +} +``` + +So, you can pass the previous `cart` parameter inside the new `context` paramter. + +Furthermore, these methods are now expected to return `PaymentSessionResponse`. It is made up of the following properties: + +```ts +type PaymentSessionResponse = { + update_requests: { customer_metadata: Record } + session_data: Record +} +``` + +Where `session_data` would include the previously returned data from these methods. The property `update_requests` allows you to pass data from the payment provider plugin to the core to update internal resources. Currently, it can only be used to update the `metadata` field of the customer entity. diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index 290528d71f..b3f6a846a8 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -176,18 +176,13 @@ module.exports = { items: [ { type: "doc", - id: "advanced/backend/upgrade-guides/1-3-0", - label: "v1.3.0" + id: "advanced/backend/upgrade-guides/1-7-1", + label: "v1.7.1" }, { type: "doc", - id: "advanced/backend/upgrade-guides/1-3-6", - label: "v1.3.6" - }, - { - type: "doc", - id: "advanced/backend/upgrade-guides/1-3-8", - label: "v1.3.8" + id: "advanced/backend/upgrade-guides/1-7-0", + label: "v1.7.0" }, { type: "doc", @@ -196,8 +191,18 @@ module.exports = { }, { type: "doc", - id: "advanced/backend/upgrade-guides/1-7-0", - label: "v1.7.0" + id: "advanced/backend/upgrade-guides/1-3-8", + label: "v1.3.8" + }, + { + type: "doc", + id: "advanced/backend/upgrade-guides/1-3-6", + label: "v1.3.6" + }, + { + type: "doc", + id: "advanced/backend/upgrade-guides/1-3-0", + label: "v1.3.0" }, { type: "doc",