conductor/docs/TUTORIAL.md

Conductor Tutorial: Build and Publish a REST Application

This tutorial uses a ready-made two-page project to introduce Conductor's main features. You will import it, run REST actions, inspect bindings, modify the visual design, save it, and publish it as a standalone application.

Allow about 25 minutes. You need an administrator account because project authoring and publishing are administrator functions.

What you will build

The companion Post Workshop project uses the public JSONPlaceholder training API. It contains:

• two pages with automatic navigation and button navigation;
• Labels, Text Input, Text Area, Buttons, Status Panel, Table, and JSON Viewer components;
• a global typed variable;
• GET and POST REST actions;
• component and variable request templates;
• a page onLoad action and Button onClick actions;
• action-response bindings and a Table-selection binding; and
• public-publishing-compatible anonymous actions.

JSONPlaceholder simulates writes but does not save them. Do not enter private, confidential, or production information; tutorial field values are sent to a public third-party service. Its behavior is documented in the JSONPlaceholder guide.

1. Import the project

1. Download or open examples/project-definitions/valid-conductor-tutorial.json from the Conductor source bundle.
2. Sign in to Conductor as an administrator.
3. Open JSON Editor.
4. Select all existing JSON and replace it with the complete contents of valid-conductor-tutorial.json.
5. Select Apply.
6. Confirm the validation summary reports no errors, then open Visual Editor.

Applying JSON changes the in-memory project; it does not save it to the database. If Apply fails, confirm you copied the entire file and that schemaVersion remains 0.1.0.

2. Tour the Visual Editor

The Create a Post page should be selected. Notice these parts of the workspace:

• The project command area shows the project name and New, Save, Load, and Preview controls.
• The page ribbon switches pages and changes page names, slugs, order, navigation visibility, and lifecycle events.
• The component palette adds controls to the active page.
• The canvas shows the application layout.
• Selection edits the selected component's identity, position, size, properties, appearance, and events.

Select Post title, Post body, Create post, and API response in turn. Observe how Text Input, Text Area, Button, and JSON Viewer expose different properties.

Try one harmless visual change:

1. Select the heading.
2. Change its displayed text to My REST Post Workshop.
3. Move or resize it on the canvas.

The dot beside the project name indicates an unsaved canonical change.

3. Run the POST action

1. Open Preview.
2. Change the post title and body if desired, using only non-sensitive tutorial text.
3. Select Create post.

The Status Panel should show created ID 101, and the JSON Viewer should display the simulated response. This single interaction demonstrates:

Button onClick
  → Create simulated post action
  → component and variable template interpolation
  → server-side POST request
  → response bindings
  → Status Panel and JSON Viewer runtime updates

Return to JSON Editor and notice that your Preview inputs, response, and ID were not written into the project. Preview state is intentionally ephemeral.

4. Inspect the action and templates

Open Actions & Bindings, expand REST Actions, and open Create simulated post.

The action sends POST https://jsonplaceholder.typicode.com/posts with a JSON content type. Its request body uses these values:

{{components.postTitle.value}}
{{components.postBody.value}}
{{variables.defaultUserId}}

Component values come from the page that invoked the action. defaultUserId is a global number variable with default value 1.

Use Test Action only to understand its limitation: action testing has no interactive Preview component state. Template-driven actions should be exercised from Preview, where the components have runtime values.

5. Inspect the response bindings

In Actions & Bindings, expand Response Bindings. The POST action has two onSuccess bindings:

Source	Target	Result
actions.action_create_post.response.body.id	components.createdPostId.value	Shows the returned ID in the Status Panel.
actions.action_create_post.response.body	components.createResponse.value	Shows the complete body in the JSON Viewer.

Bindings move response data into runtime component properties. They do not modify authored defaults or save API responses in project JSON.

6. Explore pages, page events, and tables

1. Return to Preview.
2. Select Browse sample posts or use the automatic page navigation.
3. Wait for the table to populate.
4. Select any table row.

Opening Browse Posts for the first time triggers its page onLoad event, which runs Load sample posts. Its response body is bound to components.postsTable.rows.

Selecting a row triggers a different kind of binding:

components.postsTable.selectedRow
  → components.selectedPost.value
  → onChange

The JSON Viewer displays the selected record without making another REST request. Select Refresh posts to run the GET action explicitly, then use Back to create to exercise button-based page navigation.

7. Change a variable

Open Actions & Bindings, expand Variables, and inspect defaultUserId.

This global number is used by both actions:

• the POST body assigns the simulated post to that user; and
• the GET query filters the table by that user.

Change its default from 1 to 2, return to Preview, and reload or re-enter the Browse page. The table should now show posts for user 2. This illustrates how one declared value can drive several request fields.

8. Add a component

Return to Visual Editor and add one component of your choice. For example:

1. Select the Create a Post page.
2. Add a Checkbox.
3. Name it reviewedTutorial.
4. Set its label to I reviewed this tutorial.
5. Move it beneath the navigation button.

Preview the application and interact with it. The checkbox value exists only during that loaded Preview session unless you deliberately use it in a request template.

9. See validation protect the project

1. Open JSON Editor.
2. Find the Create post Button's actionId value: action_create_post.
3. Temporarily change it to missing_action.
4. Select Apply.

Conductor should report a semantic reference error and preserve the last valid project. Correct the value or select Revert. This is the same validation gate used by Apply, Save, Update, Load, and Publish.

10. Save and reload

1. Return to Visual Editor.
2. Select Save.
3. If prompted, keep the name Conductor Tutorial — Post Workshop or choose a unique tutorial name.
4. Make another small edit and select Update.
5. Select New, confirm the discard prompt only if no unsaved work remains, then select Load and reopen the tutorial project.

The authored pages, components, actions, bindings, and variable should return. Preview-only values and API responses should not.

11. Review history

Open Execution History. The GET and POST attempts should appear with method, sanitized URL, outcome, duration, status, size, and a bounded response preview.

History is for troubleshooting. It does not store request or response headers, cookies, credentials, or sensitive query values. Use Clear history only when you intentionally want to remove all retained execution records.

12. Publish the application

Because both tutorial actions use anonymous authentication, the project can be published publicly.

1. Confirm the project is saved and valid.
2. Open Publishing.
3. Select the tutorial project.
4. Enter a display name and a unique slug such as post-workshop.
5. Choose Public or Restricted to users.
6. Select Publish, then Open app.
7. Test both pages and refresh the /apps/<slug>/browse-posts deep link directly.

Saving the source project does not update the live snapshot. Make a visible source edit, save it, and use Republish to learn that lifecycle. Unpublish removes public access without deleting the source project.

13. Where credentials fit

This tutorial deliberately uses anonymous actions. For a real protected API:

1. An administrator creates an encrypted credential under Actions & Bindings → Secrets.
2. The action selects its authentication type and the compatible opaque secret reference.
3. Conductor injects the credential server-side; it never places the value in project JSON or the published browser application.

Public applications cannot contain credential-backed actions. Choose restricted visibility for such an application. Never paste credentials into URLs, headers, templates, tutorial data, or JSON.

Next steps

• Use the User Guide as the feature reference.
• Use the Project Schema when editing JSON directly.
• Use the Administrator Guide for accounts, credentials, publishing, and security boundaries.
• Use Troubleshooting if a request or published route fails.