├── Address_Selection_Web_Form.json ├── Address_Details_Web_Form.json └── README.md /Address_Selection_Web_Form.json: -------------------------------------------------------------------------------- 1 | {"id":"a5e9759c-xxxx-xxxx-xxxx-244727276489","accountId":"7cf855bc-xxxx-xxxx-xxxx-af4f43e7021d","isPublished":true,"isEnabled":true,"hasDraftChanges":false,"formState":"active","formProperties":{"name":"Address Selection Web Form","isPrivateAccess":false},"formMetadata":{"source":"blank","createdDateTime":"2024-11-18T20:27:27.310Z","publishedSlug":"5c983ac6a214c23127b69708ec92a355","owner":{"userId":"e7c505bc-xxxx-xxxx-xxxx-0d424ff2bb5c","userName":"Donna Developer"},"lastModifiedDateTime":"2024-11-18T20:27:35.548Z","lastModifiedBy":{"userId":"e7c505bc-xxxx-xxxx-xxxx-0d424ff2bb5c","userName":"Donna Developer"},"publishedComponentNames":{"TextBox_MiV6QsjQ":"TextBox"},"admModelNamespace":"docusign.forms._7cf855bc_8a06_4544_b396_af4f43e7021d._a5e9759c_da1e_4120_b7fc_244727276489","formContentModifiedBy":{"userId":"e7c505bc-xxxx-xxxx-xxxx-0d424ff2bb5c","userName":"Donna Developer"},"formContentModifiedDateTime":"2024-11-18T20:27:27.310Z","admModelVersion":"1.0.0","type":"standalone","formPropertiesModifiedBy":{"userId":"e7c505bc-xxxx-xxxx-xxxx-0d424ff2bb5c","userName":"Donna Developer"},"formPropertiesModifiedDateTime":"2024-11-18T20:27:27.310Z","lastPublishedBy":{"userId":"e7c505bc-xxxx-xxxx-xxxx-0d424ff2bb5c","userName":"Donna Developer"},"lastPublishedDateTime":"2024-11-18T20:27:35.548Z","lastEnabledBy":{"userId":"e7c505bc-xxxx-xxxx-xxxx-0d424ff2bb5c","userName":"Donna Developer"},"lastEnabledDateTime":"2024-11-18T20:27:35.548Z"},"formContent":{"components":{"Root_Of_Journey":{"text":"","children":["Welcome_IO7aBe3q","Step_mdYOEMgS","Summary_qPygWd1O","FormSubmitAction_A8_oJ9Jn","Thankyou_HrUQwZk6"],"componentKey":"Root_Of_Journey","componentType":"Root","componentName":"Root_Of_Journey","componentRules":{}},"Welcome_IO7aBe3q":{"text":"Welcome","subText":"Extension Apps workshop for Discover 11/20","startButtonText":"Start","componentKey":"Welcome_IO7aBe3q","componentType":"Welcome"},"Step_mdYOEMgS":{"componentKey":"Step_mdYOEMgS","componentType":"Step","componentName":"Step_mdYOEMgS","text":"Choose an address record","children":["TextBox_MiV6QsjQ"],"subText":"Your selection will be used to populate the default values for updating or creating a new address record. "},"Summary_qPygWd1O":{"text":"Summary","subText":"Please review the information you have entered:","componentKey":"Summary_qPygWd1O","componentType":"Summary"},"FormSubmitAction_A8_oJ9Jn":{"componentKey":"FormSubmitAction_A8_oJ9Jn","componentType":"FormSubmitAction"},"Thankyou_HrUQwZk6":{"text":"Thank you","subText":"We've received your form.","showConfirmationButton":false,"confirmationButtonText":"Done","confirmationButtonUrl":"","componentKey":"Thankyou_HrUQwZk6","componentType":"Thankyou"},"TextBox_MiV6QsjQ":{"label":"Address ID","maxLength":4000,"componentKey":"TextBox_MiV6QsjQ","componentType":"TextBox","componentName":"TextBox_MiV6QsjQ","description":"This should correspond to the \"Id\" property of the desired address record in the src/db/Address.json file in your local copy of the data IO reference implementation."}},"isStandalone":true,"templates":[]},"formLocale":"en","versionId":1,"eSignTemplates":[]} -------------------------------------------------------------------------------- /Address_Details_Web_Form.json: -------------------------------------------------------------------------------- 1 | {"id":"89ddcf70-xxxx-xxxx-xxxx-c72a7a0a8606","accountId":"7cf855bc-xxxx-xxxx-xxxx-af4f43e7021d","isPublished":true,"isEnabled":true,"hasDraftChanges":false,"formState":"active","formProperties":{"name":"Address Details Web Form","isPrivateAccess":false},"formMetadata":{"source":"blank","createdDateTime":"2024-11-18T20:26:59.109Z","publishedSlug":"b40405f455907855b13320286946ac65","owner":{"userId":"e7c505bc-xxxx-xxxx-xxxx-0d424ff2bb5c","userName":"Donna Developer"},"lastModifiedDateTime":"2024-11-18T21:37:14.649Z","lastModifiedBy":{"userId":"e7c505bc-xxxx-xxxx-xxxx-0d424ff2bb5c","userName":"Donna Developer"},"publishedComponentNames":{"TextBox_JlfOZIfn":"TextBox","TextBox_SHC3vncu":"TextBox","TextBox_KWPPhzDY":"TextBox","TextBox_i7sUmlAc":"TextBox","TextBox_ZliSOrix":"TextBox","TextBox_d2XrAf0W":"TextBox","TextBox_ogTfEl9X":"TextBox","TextBox_8F6nFlh3":"TextBox"},"admModelNamespace":"docusign.forms._7cf855bc_8a06_4544_b396_af4f43e7021d._89ddcf70_dc78_4c56_8e19_c72a7a0a8606","formContentModifiedBy":{"userId":"e7c505bc-xxxx-xxxx-xxxx-0d424ff2bb5c","userName":"Donna Developer"},"formContentModifiedDateTime":"2024-11-18T21:37:10.575Z","admModelVersion":"1.1.0","type":"standalone","formPropertiesModifiedBy":{"userId":"e7c505bc-xxxx-xxxx-xxxx-0d424ff2bb5c","userName":"Donna Developer"},"formPropertiesModifiedDateTime":"2024-11-18T20:26:59.109Z","lastPublishedBy":{"userId":"e7c505bc-xxxx-xxxx-xxxx-0d424ff2bb5c","userName":"Donna Developer"},"lastPublishedDateTime":"2024-11-18T21:37:14.649Z","lastEnabledBy":{"userId":"e7c505bc-xxxx-xxxx-xxxx-0d424ff2bb5c","userName":"Donna Developer"},"lastEnabledDateTime":"2024-11-18T21:37:14.649Z"},"formContent":{"components":{"Root_Of_Journey":{"text":"","children":["Step_Kf8fVZRp","Summary_10gQJIDM","FormSubmitAction_4haZfV1e","Thankyou_kOBmQZwc"],"componentKey":"Root_Of_Journey","componentType":"Root","componentName":"Root_Of_Journey","componentRules":{}},"Step_Kf8fVZRp":{"componentKey":"Step_Kf8fVZRp","componentType":"Step","componentName":"Step_Kf8fVZRp","text":"Address Details","children":["TextBox_JlfOZIfn","TextBox_SHC3vncu","TextBox_KWPPhzDY","TextBox_i7sUmlAc","TextBox_ZliSOrix","TextBox_d2XrAf0W","TextBox_ogTfEl9X","TextBox_8F6nFlh3"],"subText":"Fill in this form to update or create a new Address record"},"Summary_10gQJIDM":{"text":"Summary","subText":"Please review the information you have entered:","componentKey":"Summary_10gQJIDM","componentType":"Summary"},"FormSubmitAction_4haZfV1e":{"componentKey":"FormSubmitAction_4haZfV1e","componentType":"FormSubmitAction"},"Thankyou_kOBmQZwc":{"text":"Thank you","subText":"We've received your form.","showConfirmationButton":false,"confirmationButtonText":"Done","confirmationButtonUrl":"","componentKey":"Thankyou_kOBmQZwc","componentType":"Thankyou"},"TextBox_JlfOZIfn":{"label":"Address ID","maxLength":4000,"componentKey":"TextBox_JlfOZIfn","componentType":"TextBox","componentName":"TextBox_JlfOZIfn","description":"If the Address ID matches an entry in src/db/Address.json, the corresponding record will be updated with the information in this form. Otherwise, a new record will be created."},"TextBox_SHC3vncu":{"label":"Address Name","maxLength":4000,"componentKey":"TextBox_SHC3vncu","componentType":"TextBox","componentName":"TextBox_SHC3vncu"},"TextBox_KWPPhzDY":{"label":"Street 1","maxLength":4000,"componentKey":"TextBox_KWPPhzDY","componentType":"TextBox","componentName":"TextBox_KWPPhzDY"},"TextBox_i7sUmlAc":{"label":"Street 2","maxLength":4000,"componentKey":"TextBox_i7sUmlAc","componentType":"TextBox","componentName":"TextBox_i7sUmlAc"},"TextBox_ZliSOrix":{"label":"Locality","maxLength":4000,"componentKey":"TextBox_ZliSOrix","componentType":"TextBox","componentName":"TextBox_ZliSOrix"},"TextBox_d2XrAf0W":{"label":"Subdivision","maxLength":4000,"componentKey":"TextBox_d2XrAf0W","componentType":"TextBox","componentName":"TextBox_d2XrAf0W"},"TextBox_ogTfEl9X":{"label":"Country or Region","maxLength":4000,"componentKey":"TextBox_ogTfEl9X","componentType":"TextBox","componentName":"TextBox_ogTfEl9X"},"TextBox_8F6nFlh3":{"label":"Postal Code","maxLength":4000,"componentKey":"TextBox_8F6nFlh3","componentType":"TextBox","componentName":"TextBox_8F6nFlh3"}},"isStandalone":true,"templates":[]},"formLocale":"en","versionId":2,"eSignTemplates":[]} -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # discover-extension-apps-workshop 2 | Find all the resources you need for the Extend workshop for Discover 11/20! 3 | 4 | # Extension Apps Workshop: step-by-step instructions 5 | 6 | # Prerequisites: 7 | 8 | * A free Docusign Developer account 9 | * IDE of choice 10 | * Install the necessary software: 11 | * Node.js and npm 12 | * Ngrok 13 | 14 | # Step 1: Download and set up the reference implementation 15 | 16 | **Note**: If you have not already done so, install the necessary software listed in the prerequisites for this exercise. 17 | 18 | * If you are following along with the workshop activity, please download or clone the Data IO reference implementation from GitHub at: 19 | * [https://github.com/docusign/extension-app-data-io-reference-implementation](https://github.com/docusign/extension-app-data-io-reference-implementation) 20 | * Use the instructions in the README for this project to: 21 | * Generate secret values and place them in your local .env file 22 | * Install dependencies and run the app in development mode 23 | * Start ngrok to receive a public URL that forwards traffic to localhost:3000 24 | 25 | # Step 2: Register an extension app on the Developer Console 26 | 27 | There are two methods to register your extension app on the Developer console. You can either: 28 | 29 | * Prepare the example manifest file locally and upload it to the Developer Console. Or, 30 | * Create a manifest file within the Developer Console using the user-friendly form-based experience. 31 | 32 | ## To prepare the example manifest file locally 33 | 34 | * Edit your local copy of the [manifest.json](https://github.com/docusign/extension-app-data-writeback-reference-implementation-private/blob/main/manifest.json) file. 35 | * Update all instances of \ to the forwarding address generated by ngrok. 36 | * Update \ and \ variables with the corresponding environment variables OAUTH\_CLIENT\_ID and OAUTH\_CLIENT\_SECRET respectively. 37 | 38 | ## To create a manifest within the Developer Console using the form-based experience: 39 | 40 | * Navigate to [https://devconsole.docusign.com](https://devconsole.docusign.com)/apps 41 | * Select Create app → Using a form-based experience. 42 | * Fill in the form as follows: 43 | * Tell us about your app (fill in the following fields as you like): 44 | * App name 45 | * Published by 46 | * Support email 47 | * Who are you building this for? 48 | * Select Public. 49 | * What type of app are you building? 50 | * Select Data Input Output. 51 | * Data Input Output Type 52 | * Select Data Read and Write. 53 | * Select **Create App.** 54 | * Select **Edit your connection, extensions, and actions using the integration details page.** 55 | * **Edit** your Connection. 56 | * Parameters: 57 | * Scopes: \[\]. 58 | * Client ID: copy the corresponding OAUTH\_CLIENT\_ID variable from your .env file. 59 | * Client Secret: copy the corresponding OAUTH\_CLIENT\_SECRET variable from your .env file. 60 | * Custom Config: 61 | * Replace the base URL with your ngrok forwarding address for: 62 | * Authorization URL. 63 | * Token URL. 64 | * **Save** your connection. 65 | * **Edit** your Data Read & Write extension. 66 | * Update the Params URI for each action by replacing the base URL with your ngrok forwarding address. 67 | * **Save** your extension. 68 | 69 | # Step 3: Test your connection and extensions on the Developer Console 70 | 71 | * After saving your manifest on the Developer Console, navigate to the Testing tab for your new extension app. 72 | * Install your extension app to your developer account. 73 | * On the row displaying your connection, click “Run Test” 74 | * Once your connection has been tested successfully, you can execute extension tests. 75 | * Test each extension by clicking “Run Test” and using the instructions from the [README](https://github.com/docusign/extension-app-data-io-reference-implementation?tab=readme-ov-file#extension-tests). 76 | 77 | # Step 4: Upload a web form to your Developer account 78 | 79 | Use the JSON config files included in this repo to upload the required webforms to your developer account. 80 | 81 | * Go to the **Templates** tab in your developer account. 82 | * Select **Start** → **Web Forms** → **Upload Web Form** 83 | * Upload the following web form config files: 84 | * [Address\_Selection\_Web\_Form.json](Address_Selection_Web_Form.json) 85 | * [Address\_Details\_Web\_Form.json](Address_Details_Web_Form.json) 86 | 87 | 88 | 89 | 90 | # Step 5: Create a Maestro Workflow 91 | 92 | Go to the **Agreements** tab in your developer account and select **Maestro Workflows.** Then, select **Create Workflow → Create Workflow** 93 | 94 | ## Add a workflow starting point 95 | 96 | This will determine where your workflow will start from: a link, from within Maestro, or from an API call. 97 | 98 | 1. Select **Add workflow start** and choose **From wIthin Maestro** from the dropdown. 99 | 2. Select **Apply.** 100 | 101 | ## Collect data with web forms \- Address selection 102 | 103 | This step will use [Address\_Selection\_Web\_Form.json](Address_Selection_Web_Form.json) to collect an Address ID from the user. This will be used in the next step to search for a record in your local database that matches the address ID provided. 104 | 105 | 1. **Add Step** → **Collect Data with Web Forms** 106 | 2. Select **Configure** 107 | 3. Under **Which form would you like to use?** Select **Address Selection Web Form** from the drop down. 108 | 4. Select **Next** 109 | 5. Under **Who will participate in this step?** Select **Add Participant** from the drop down. 110 | 6. Select **Add Another Participant** from the pop up window. 111 | 7. Enter a role name for the participant. For example, “participant1”. 112 | 8. **Save** your participant info. 113 | 9. Select your newly created participant from the drop down menu under **Who will participate in this step?** 114 | 10. Select **Apply.** 115 | 116 | ## Read from Extension App 117 | 118 | This step will search for a record in your local database and save the associated properties as variables in your workflow. 119 | 120 | 1. Select the \+ icon to **Add a step.** 121 | 2. Select **Read from {EXTENSION\_APP\_NAME}**. For example, if you are using the provided example manifest, this will be **Read from Data IO App**. 122 | 3. Select **Configure**. 123 | 4. Under **Where will you read from?**, use the default connection and select **Address** as the object. 124 | 5. Select **Next.** 125 | 6. Under **Which record are you reading from?** Select **Add rule**. 126 | 7. Configure the rule as follows 127 | 1. Extension App Field: select **Address ID** from the drop down. 128 | 2. Operator: **\=** 129 | 3. Workflow field: select **Collect Data from Web Forms** → **Address ID** from the drop down. 130 | 8. Select **Save and Exit.** 131 | 9. Select **Next.** 132 | 10. Under **Which fields would you like to read?** choose **Select Fields.** 133 | 11. Choose **Select All.** 134 | 12. Select **Save and Exit.** 135 | 13. Select **Apply.** 136 | 137 | ## Collect data with web forms \- Account details 138 | 139 | This step will use [Address\_Details\_Web\_Form.json](Address_Details_Web_Form.json) to collect account details from the user. This web form will be prepopulated with the data obtained in the previous step from your local database. 140 | 141 | 1. Select the \+ icon to **Add a step.** 142 | 2. Select **Collect Data with Web Forms.** 143 | 3. Select **Configure.** 144 | 4. Under **Which form would you like to use?** Select **Address Details Web Form** from the drop down. 145 | 5. Select **Next.** 146 | 6. Select your previously created participant from the drop down menu under **Who will participate in this step?** 147 | 7. Select **Continue to map data fields →.** 148 | 8. For each field listed, choose **Read from extension app** in the dropdown and select the corresponding value. 149 | 9. Select **Apply.** 150 | 151 | ## Writeback to Extension App 152 | 153 | 1. Select the \+ icon to **Add a step.** 154 | 2. Select **Writeback to {EXTENSION\_APP\_NAME}**. For example, if you are using the provided example manifest, this will be **Writeback to Data IO App**. 155 | 3. Select **Configure.** 156 | 4. Under **Where will you write to?**, use the default connection and select **Address** as the object. 157 | 5. Under **Which record are you writing to?** Select **Add rule**. 158 | 6. Configure the rule as follows 159 | 1. Extension App Field: select **Address ID** from the drop down. 160 | 2. Operator: **\=** 161 | 3. Workflow field: select **Collect Data from Web Forms 2** → **Address ID** from the drop down. 162 | 7. Select **Next.** 163 | 8. Under **Which fields are you writing to?** choose **Manage Fields.** 164 | 9. Choose **Select All.** 165 | 10. Select **Save and Exit.** 166 | 11. For each field listed, choose **Collect Data from Web Forms 2** in the dropdown and select the corresponding value. 167 | 12. Select **Apply.** 168 | 169 | ## Add Confirmation Screen 170 | 171 | 1. Select the \+ icon to **Add a step.** 172 | 2. Select **Show a Confirmation Screen.** 173 | 3. Select **Configure** 174 | 4. Under **Participant who will see messages** select your previously created participant. 175 | 5. Select **Apply.** 176 | 177 | # Step 6: Publish workflow 178 | 179 | Review and publish your workflow. 180 | 181 | 1. In the upper right corner of the Maestro Workflow Editor, select **Review & Publish.** 182 | 2. Name your workflow. 183 | 3. If your workflow is valid and ready to publish you should see a green banner with the text “This workflow is ready to publish. 184 | 4. Select **Publish.** 185 | 5. You should see a pop-up appear on your screen, select **Authorize My Account.** 186 | 6. Select **Publish.** 187 | 7. Select **Go to Workflows.** 188 | 189 | # Step 7: Run workflow 190 | 191 | 1. Once your workflow has successfully published, click on the menu for your new created workflow and select **Run Workflow.** 192 | 2. Name your instance. 193 | 3. Follow the instructions in the web forms to fill in the necessary web form fields. 194 | 195 | Your records should be updated in your local database. 196 | --------------------------------------------------------------------------------