# Partners Partners represent the trading partners you exchange EDI documents with. Each partner brings together the envelopes, connection, webhooks, and transaction settings needed to process EDI -- and from that configuration, Tediware builds the processing flows that handle your documents automatically. ## Creating a Partner 1. Navigate to **Partners** and click **Add Partner** 2. Fill in the required fields: - **Name** -- a display label for your reference. Not visible to trading partners. - **Key** -- a unique identifier for this partner, used in API endpoints and internal references. Must be 3-50 characters, uppercase letters, numbers, and underscores only. The key cannot be changed after creation. - **Starting Interchange Control Number** -- the first interchange control number to use. Defaults to 1000. - **Starting Group Control Number** -- the first group control number to use. Defaults to 1000. - **Tags** -- optional labels for organizing your partners. 3. Click **Create** ## Configuring a Partner After creating a partner, open it from the partner list to access the detail page. The **Configuration** card contains the settings that define how this partner communicates: - **Internal Envelope** -- your organization's EDI identity (sender for outbound, receiver for inbound) - **External Envelope** -- the trading partner's EDI identity - **Connection** -- the SFTP, AS2, or API connection used to exchange files with this partner - **Inbound Webhook** -- notified when EDI documents are received and processed from this partner - **Outbound Webhook** -- notified when EDI documents are successfully delivered to this partner (optional) - **Error Webhook**: notified when processing errors occur (optional). Use a different webhook from the outbound slot: the two deliveries send the same body, so one endpoint serving both cannot tell delivered from failed on arrival. After making changes, click **Save** to persist the configuration. ### Requesting a partner connection If your organization has the VAN add-on, the partner page has a **Request connection** button. Use it when a partner is not yet reachable through your VAN connection. The form is prefilled from the partner's external envelope. Do not include passwords, keys, or certificates. Anything confidential is arranged directly with your partner by our provisioning team. The request is emailed to you and to our team, and we email you again once the partner is connected. If your VAN connection is still being set up, the request is queued until it is ready. ## Control Numbers EDI transmissions include control numbers in their ISA and GS headers to uniquely identify each interchange and group. Tediware automatically increments these numbers with each transmission sent to the partner. The partner detail page displays the current control number values. To adjust the starting point, click **Settings** and update the starting interchange or group control number. The next transmission will use whichever value is higher -- the starting number you set or the next number in the existing sequence. ## Transaction Settings Transaction settings define which X12 document types you exchange with a partner. Each setting specifies a transaction set (e.g., 810 Invoice, 850 Purchase Order) and its direction. ### Inbound Inbound transaction settings identify the document types you receive from the partner. Tediware parses inbound EDI using the standard X12 specification, so an inbound setting works with no further configuration: by default you receive the translated JSON as-is. Optionally, assign an **inbound mapping** to normalize this partner's documents into your canonical shape before delivery. The mapping list offers inbound mappings whose canonical implementation matches the setting's transaction set code, regardless of X12 release, so one canonical 850 can serve partners on 4010 and 5010 alike. See the Mappings documentation for when inbound mappings are worth adopting and how to set one up. An inbound setting never has an implementation of its own; the canonical implementation belongs to the mapping. Inbound flows build and run the same way with or without a mapping assigned. To add one, click **Add** in the Inbound Transaction Settings section, select the transaction set, and optionally assign a mapping. ### Outbound Outbound transaction settings identify the document types you send to the partner. Each outbound setting requires either: - An **implementation** -- the partner-specific EDI specification that governs how the document is structured - A **mapping** with an associated implementation -- a JSONata transformation that converts your JSON data into the format defined by the implementation With an implementation alone, the JSON you submit must match that implementation's schema directly. That is a fair choice when this partner is the only one you will ever send the document to, and a mapping is one more thing to maintain. It stops being fair at the second partner: guides differ, so your code ends up building a different payload per partner. With a mapping, you submit one shape for the transaction set regardless of partner, and each partner's mapping turns it into that partner's EDI. See the Mappings documentation for how sources are shared across partners. The detail page shows the API endpoint for each outbound transaction set (e.g., `/partners/ACME/ts/810`), which you use to submit data for processing. To add one, click **Add** in the Outbound Transaction Settings section, select the transaction set, and assign an implementation and optionally a mapping. ### Test and Production Each transaction setting has a **Usage indicator**, Production (P) or Test (T), which is the X12 ISA15 value. It is in the **Advanced** section of the setting form and defaults to Production. Because it is set per transaction setting, a partner's 850 can be in production (P) while their 856 is in test (T), with both using the same connection and flows. In practice, many trading partners provide test credentials (e.g. a test SFTP) during the onboarding process, and will happily send and receive transactions with a production (P) usage indicator, so you may never need to change the default for this setting even during the testing process. However, for those trading partners who do expect test traffic to feature the T usage indicator, here is how it works in Tediware. - On an **outbound** setting, this is the ISA15 usage indicator Tediware sends on every interchange for that set. Switch it to Production when the partner confirms testing is successful and you are ready to transition to live, production data. To send a single document with the other value, use `overrides.usageIndicator` on the send request (see the API documentation for outbound EDI). - On an **inbound** setting, this is the usage indicator you expect the partner to send. Tediware records the ISA15 that arrives on each transaction and processes test and production documents the same way, through the same flow and to the same webhook. A document whose ISA15 differs from the setting is still processed, and carries a `usage_indicator_mismatch` warning. Test transactions show a **T** badge on the EDI Transactions list, and the Prod/test filter narrows the list to one or the other. The API returns the value as `usageIndicator` on the transaction and on the results for it, so your system can decide what to do with a test document before it creates orders or updates records. An automatic 997 goes out with the same ISA15 as the interchange it acknowledges. Test transactions are billed like production ones. The sandbox partner's transaction settings are set to Test, and its sample documents arrive as test documents. If your code skips test documents, it skips the sandbox's too, so an empty result there can mean the check is working. ### Remote Directory When a partner uses an SFTP connection, each transaction setting has an optional **Remote Directory** field, found in the **Advanced** section of the setting form. By default, Tediware fetches inbound files from, and uploads outbound files to, the directories set on the connection. A Remote Directory on a transaction setting overrides that default for just that document type. Leave it blank to use the connection's default directory. Inbound fetches still poll the connection's default directory as well, so a transaction setting without an override is always covered. The field does not apply to non-SFTP connections, or to VAN-routed connections where all files use the connection's default directory. ## Flows Flows are the processing pipelines that Tediware builds from your partner configuration. There are two flows per partner -- one for inbound documents and one for outbound. ### Building a Flow Once the partner's configuration is complete (envelopes, connection, webhooks, and at least one transaction setting), the **Flows** card on the partner detail page enables the **Build** button. Click it to generate the flow. If the button is disabled, hover over it to see which configuration is missing. ### Flow Status After building, each flow shows its status: - **Active** -- the flow is live and processing documents - **Pending** -- the flow has been built but is not yet active Click the flow name to navigate to its detail page. The inbound flow also shows a **Testing endpoint**. POST an EDI file to it to run the inbound flow without going through the connection, which is how a test suite exercises the flow and how you check a new inbound mapping against a partner's sample before the partner sends real traffic. The document must be a complete interchange, the flow must be active, and the submission appears in the transaction list like any other inbound document. The request format is in the API reference under Inbound EDI. ### When Changes Go Live Saving a partner doesn't change the flows that process its documents. Each flow keeps running on its previous configuration until you rebuild it, so you can make and review several changes before any of them reach live traffic. Flows with saved changes that aren't live yet show **Changes not live**. Click **Rebuild** when you're ready. Two fields on a transaction setting are read each time a document is processed, so they take effect as soon as you save, with no rebuild: **Usage indicator** and **Remote Directory**. ## Automatic 997 Acknowledgments A 997 Functional Acknowledgment is the EDI message that tells a trading partner "we received your file." Tediware can generate and send a 997 automatically for every inbound EDI interchange it receives from a partner. Enable it on the **Configuration** card of the partner detail page via **Automatically send 997 acknowledgments**. ### What auto-ack validates The 997 is an **envelope-layer acknowledgment**. It confirms that an inbound interchange arrived and that its envelope follows X12 syntax rules. It does **not** confirm that the data inside the document makes business sense, that your downstream systems accepted it, or that any order, shipment, or claim will be fulfilled. Tediware checks the envelope of every inbound file: - ST and SE control numbers agree, and the SE segment count matches the actual number of segments. - GS and GE control numbers agree, and the GE transaction set count matches the actual number of transaction sets. - No transaction set or group is missing its trailer (as in a truncated file). - The X12 release (ISA12/GS08) is one Tediware supports. - Each transaction set is one this partner is configured to send you. Each 997 reports one of three outcomes: - **Accepted** (`AK5*A`, `AK9*A`). The envelope is clean. This is the normal case. - **Accepted, but errors were noted** (`AK5*E`, `AK9*E`). The envelope has syntax errors (for example, a segment count that doesn't add up), but Tediware processed the document anyway. The 997 carries the standard error codes so the partner can fix their side. - **Rejected** (`AK5*R`, `AK9*R`). Tediware could not process the document: the X12 release is not supported, or the transaction set is not configured for this partner. A 997 is sent even when a file cannot be parsed, as long as its ISA and GS headers are readable. Only a file with no readable ISA or GS produces no 997, because there is no addressable envelope to acknowledge. Tediware does not yet emit segment- and element-level error detail (`AK3`/`AK4`). ### Who should turn this on Turn it on when your trading partner expects a 997 for every inbound file and you don't already generate one yourself. This is the common case for partners who treat EDI as plumbing and rely on their counterparty to provide envelope-layer acknowledgment. Leave it off when: - You (or a system upstream of Tediware) already send 997s based on your own business processing; enabling auto-ack would result in duplicate 997s. - Your trading partner's contract requires 997s that reflect business validation outcomes (the automatic 997 reports envelope syntax, not what your downstream systems did with the data). - You exchange HIPAA traffic and your partner expects a 999 Implementation Acknowledgment; 999 support is not yet available. ### What to monitor - **Ack volume per partner.** A partner that suddenly stops receiving 997s after inbounds is usually a sign something has broken upstream. Tediware's logs and traces for the inbound flow will show whether the ack node ran. - **Accepted-with-errors codes.** An occasional `E` is normal when a partner sends envelope syntax errors. A partner whose files consistently come back `E` has a recurring problem on their side worth raising with them; the error codes in the 997 say what it is. ### Control numbers for 997s Outbound 997s consume interchange and group control numbers from the same pool as any other outbound document for that partner. Tediware increments them automatically. No separate configuration is required. ### Roadmap Segment- and element-level error detail (`AK3`/`AK4`) and the HIPAA 999 are on the backlog. If your trading partner has ack requirements beyond these, get in touch via **Get Support** and we can prioritize accordingly. ## Tracking 997 Acknowledgments for Outbound This is the reverse of automatic 997s above: instead of sending a 997 for documents you receive, Tediware watches for the partner's 997 replies to documents you send. When it is on, every outbound document to this partner starts out **Awaiting 997** on the [EDI Transactions](edi-transactions.md) page, then flips to **Accepted** or **Rejected** when the partner's 997 arrives, so you can search and filter by which of your sent documents the partner has acknowledged. Turn it on or off with **Track 997 acknowledgments for outbound** on the **Configuration** card. It is on by default. Leave it off for a partner that does not send you 997s, so their sent documents don't sit in an Awaiting state that will never clear. The setting only affects documents sent after you change it, and takes effect without rebuilding any flow. Matching is by group control number (GS06). A 997 reports acceptance at the envelope layer: **Rejected** means the partner's 997 reported a problem with the group, which you can inspect by opening the transaction and its trace. ## Partners with Multiple ISA Identifiers Some trading partners send or receive under more than one ISA identifier. Two common cases: - A carrier uses one ID for operational transactions (204, 990, 214) and a separate billing ID for financial transactions (210). - A retailer sends the same transaction type under different IDs for different business channels, such as drop-ship orders from one ID and ship-to-store orders from another. Start with one question: can you tell the documents apart from their contents, or only from the sender ID? - **From the contents** (a field in the document differs between the two kinds): set up one partner. Your system branches on that field. There is nothing extra to configure in Tediware. - **Only from the sender ID**: set up one partner per sender ID. Each identity then has its own transaction settings, mappings, and control number sequences, which matches how the partner actually addresses you. To set up one partner per sender ID: 1. Use one connection for all of them, with **VAN Routing** enabled. This is required even when all the traffic comes from one real-world partner: Tediware only routes inbound files by their ISA identifiers when VAN Routing is on. See the [Connections](connections.md) documentation. 2. Use one internal envelope, your own identity, for every partner. Only the external envelopes differ. 3. Create one external envelope per sender ID. 4. Create one partner per external envelope, named to show the relationship, for example `PETCO_DS` and `PETCO_STS`, or "Acme Trucking" and "Acme Trucking (Billing)". Set up the first partner, then use **Duplicate** (see below) to create the second, and change its key and external envelope. Inbound, Tediware routes each file to the partner whose envelopes match the file's ISA sender and receiver. The partner key travels with each document: every result carries it as `partner.key` (fetch the result by the `resultId` the webhook sends), and feed entries carry it as `partnerKey`. Your system tells the two kinds of document apart by the key rather than by the ISA sender ID. Outbound, submit each document to the matching partner's endpoint, for example `/platform/partners/PETCO_STS/ts/856`. Tediware puts that partner's ID in the ISA receiver. If a single partner only needs a different identifier on some outbound submissions, the outbound endpoint also accepts `overrides` that replace the envelope identifiers for one submission (see [Outbound EDI](/resources/api-docs/outbound-edi)). Overrides do not help inbound routing, which still needs one partner per sender ID. Give each partner a distinct envelope identity. If two partners on the same connection share the same ISA sender and receiver identity and both have an active inbound flow, Tediware cannot decide which one an inbound file belongs to, so neither partner receives it. When you activate an inbound flow that would create this conflict, Tediware names the conflicting partner and asks you to confirm before continuing. ## Partner Settings Click the **Settings** button on the partner detail page to open a modal where you can edit: - **Name** - **Starting Interchange Control Number** - **Starting Group Control Number** - **Tags** Changes made in the settings modal are staged locally. Click **Save** on the main page to persist them along with any other configuration changes. ### Duplicating a Partner To copy an existing partner, open it and click **Duplicate** (also available from the actions menu in the **Partners** list). This is useful when a new partner shares most of its configuration with one you already have, or when you need a second identity for the same partner. The duplicate copies the source partner's configuration (envelopes, connection, webhooks, settings, and all of its transaction settings, including any Remote Directory overrides) and its tags. A form pre-fills a new name, key, and starting control numbers so the copy does not collide with the source. Adjust them before clicking **Duplicate**. Flows are not copied. Open the new partner and rebuild its flows when you are ready. The sandbox partner cannot be duplicated. ### Deleting a Partner To delete a partner, go to the **Partners** list, find the partner, and click **Delete** in the actions column. You will be asked to confirm. Deleting a partner removes its associated flows and transaction settings.