Frequently Asked Questions

General Questions about the EPCIS Workbench

What is the EPCIS Workbench?

The EPCIS Workbench is a free, interactive tool for working with the GS1 Electronic Product Code Information Services (EPCIS) standard. The EPCIS Workbench lets you focus on the business content of EPCIS data instead of the technical details.

What is Electronic Product Code Information Services (EPCIS)?

EPCIS is a GS1 Standard for Visibility Data. EPCIS data consists of events, where each event is a record of something that happened in the real world. EPCIS data is used to track and trace products, assets, documents, and other things as they move through a business process, especially a business process that spans multiple physical locations and multiple organizations. An EPCIS event records what was involved in a business process step, when the step took place, where it took place, and additional business context that answers the question “why.”

How does the EPCIS Workbench help me work with EPCIS?

EPCIS data take the form of an eXtensible Markup Language (XML) document. This format is easy for computers to understand, not so easy for humans. The EPCIS Workbench lets you see the data content of EPCIS data in a format that is more human-friendly.

So the EPCIS Workbench decodes EPCIS data. Anything else?

Yes, much more. Besides decoding EPCIS data, the EPCIS Workbench also looks for errors and shows you where they are. You can also use the EPCIS Workbench to edit existing EPCIS data files or create new ones from scratch, all in human-friendly terms.

What about working with EPCIS repositories?

If you have an EPCIS repository, you can use the EPCIS Workbench to capture EPCIS events to your repository, to query your repository for events matching criteria you specify, and to display the results of those queries.

Is the EPCIS Workbench an “EPCIS Repository” or “EPCIS Server”?

No, the EPCIS Workbench is not an EPCIS Repository. But if you have an EPCIS Repository, the EPCIS Workbench is a very convenient way to interact with your repository (see previous question).

But it looks like I can upload EPCIS data to the EPCIS Workbench? Doesn't that make it an EPCIS Repository?

No, not really. An EPCIS Repository stores individual EPCIS events in a database, so that you can query for any or all of those events according to a query. The EPCIS Workbench lets you upload files containing EPCIS events, but it doesn't provide a way for you to query for individual events. Unlike an EPCIS Repository, the EPCIS Workbench lets you display those files in a human-friendly format, as well as modify them. An EPCIS Repository is typically capable of storing thousands or millions of events for consumption by business applications; the EPCIS Workbench is an interactive tool for humans who are working with smaller amounts of data at a time.

OK, so I don't use the EPCIS Workbench directly in production. When would I use it?

The EPCIS Workbench is a great tool for all the activities that surround a production deployment. When you're just starting an EPCIS project, you can use the EPCIS Workbench to design the data you will use in your project and to test that data you create is standards-compliant before you deploy. If you're sharing data with trading partners, you can use the EPCIS Workbench to organize the test data you send as you're getting the sharing working, and to confirm that the data you send to your partners and the data you receive from your partners has the content you expect and is standards compliant. During the testing phases of your project, you can use the EPCIS Workbench to look at test data to see if it meets your expectations. And once you're in production, you can use the EPCIS Workbench to help with figuring out exceptions and problems that arise.

Questions about Account Registration

Why do I have to register for an account?

When you upload EPCIS data to the EPCIS Workbench to decode it, or use the EPCIS Workbench to create new data, the EPCIS Workbench keeps a copy so you can view or edit it later. You need to have an account so that nobody but you can see your data.

What information do I need to provide to register?

Just your name, e-mail, company name, and your time zone.

Why do you need that information?

You use your e-mail to log in, so we need to know that to recognize you. We want your name so that we can greet you when you log in. We need to know your time zone so that we can display dates and times. And we want your company name so that we have an idea of what sorts of companies are interested in the EPCIS Workbench (but we won't mind if you leave that one blank).

Will I be asked to provide a credit card number?

No. The EPCIS Workbench is free, so we don't need your credit card number.

How will you use my e-mail address?

Right after you register, we will send you an e-mail to complete your registration. You click the link in the e-mail, which takes you to a screen where you set your password, and then your account is ready to use. After that, you enter your e-mail address and password to log in. If you ever forget your password or want to change it, we will send you another e-mail with a reset password link. If you provide feedback or ask a question through the Feedback link, we might use your e-mail to send you a reply. Finally, we may occasionally use your e-mail to notify you of new features or other changes to the EPCIS Workbench.

One thing we will not do is give your e-mail address to anybody else, for any reason.

I forgot my password; what do I do?

Just click the Forgot Password link on the home page or login screen. We will send you an e-mail with a link to reset your password.

What if I remember my password but I want to change it?

Use the Forgot Password link on the home page or login screen (even though you didn't really forget it). We will send you an e-mail with a link to reset your password.

How can I change the e-mail address for my account?

Click the Feedback link and ask for a change. We'll take care of it as soon as possible.

Questions about Event ID

What is the Event ID?

The Event ID is an optional field in an EPCIS event. When it is specified, it provides a globally unique identifier for that specific EPCIS event. Unlike other identifiers in an EPCIS event, the Event ID refers to the EPCIS event itself, not to a real-world entity. The Event ID is new in EPCIS 1.2.

Should every EPCIS event have an Event ID?

No. In fact, an Event ID is seldom needed. The only use for the Event ID described in the EPCIS standard is when an event containing an error declaration wants to refer to a subsequent event as providing a correction. This is a pretty rare situation. And even in that situation, the use of an Event ID is optional.

Why wouldn't I put an Event ID into an event?

An Event ID must be globally unique -- different from the Event ID on any other EPCIS event anywhere in the world. It is not always easy to generate such a unique identifier. Adding an Event ID places an additional burden on the EPCIS Capturing Application that creates the event, and in most cases it is not needed.

If I do want to include an Event ID, what should it be?

The EPC Core Business Vocabulary specifies that an Event ID should be a Universally Unique Identifier (UUID), specifically a UUID expressed in URI syntax according to RFC 4122 using either Version 1 (date/time+MAC) or Version 4 (random) variant. Here is an example: 

urn:uuid:48b59f5c-2635-42d8-8aa7-24f748cfaf6b
The EPCIS Workbench event editor can generate a UUID for you.

Questions about Error Declaration

What is an error declaration?

An error declaration is an optional section within an EPCIS event. An event containing an error declaration has a special meaning: it means "a previous EPCIS event should be considered to be erroneous".

Why is an error declaration needed?

In EPCIS, new events may be captured, but a previously captured event cannot be modified or deleted. This is especially important because EPCIS events may be shared between different parties -- if it were possible to modify or delete an event, it would be difficult to ensure that all parties have consistent data. So the only way to correct an error is to issue a new event whose meaning is to reverse what was implied by the erroneous event. An event containing an error declaration provides a general way to do this.

Is an error declaration always needed to correct an error?

No. In many cases, an erroneous event can be corrected with an ordinary EPCIS event, without an error declaration. For example, if an earlier aggregation event mistakenly included a child that it shouldn't have, a disaggregation event (aggregation event with action DELETE) can correct that error.

So when must an error declaration be used?

Use an error declaration when it's simply impossible to reverse the effect of an earlier event in any other way. For example, if a destruction event (an object event with action DELETE and CBV business step destroying) included an EPC that wasn't actually destroyed, there is no "undestroying" event whose meaning reverses the first event. In that case, an error declaration event can be used. Commissioning and transformation events are other examples of events that generally require an error declaration to reverse, as is any event whose event time is in error.

How does an error declaration work?

The idea of an error declaration event is that it indicates that a prior event is in error. An error declaration event looks exactly like the earlier, erroneous event, with an addition <errorDeclaration> element. Apart from the errorDeclaration element and the record time, all fields of the error declaration are exactly the same as the earlier event.

Does an error declaration use an event ID to point to the erroneous event?

No. If an error declaration required an event ID to point to the erroneous event, then all events would have to carry an event ID, because at the time an event is captured you wouldn't know if it might need to be corrected in the future. To avoid that, an error declaration event refers to the erroneous event not by an event ID, but by having its data fields be identical to the erroneous event. If you ever see an event, and another identical event that includes an <errorDeclaration> element, then you know that the second cancels out the first.

That seems complicated. Why not just use an event ID?

For two reasons. First, as noted above, it avoids requiring all EPCIS events to carry an event ID, which would create more work for capturing applications. Second, it means that if you ever make an EPCIS query, and one of the events matched by your query also has an error declaration event, the error declaration event will also match your query (because all of its fields are the same) and so you will see the error declaration in your results.

So what is the event ID for?

Sometimes when you create an error declaration event, you also create one or more additional events that contain the information that should have been in the original, erroneous event. These are called "corrective events." The error declaration can contain a forward reference to any such corrective events by using an event ID. Since you know you are creating the corrective events specifically to correct an error, you can include an event ID even though you don't normally include event IDs in ordinary events.

Is an event ID required in a corrective event?

No. You can refer to a corrective event in an error declaration using an event ID, but you don't have to. The corrective event will still have the corrective effect whether or not it is referenced by the error declaration. The event ID just makes it easier to find the corrective event if you are looking at the error declaration.

Questions about Displaying Product or Location Names

Can the EPCIS Workbench display the name of a product or location?

Yes it can. When the EPCIS Workbench displays EPCIS events, it decodes identifiers such as EPC URIs into a format that is easier to read. For example, the EPC URI urn:epc:id:sgtin:0614141.011111.400 is decoded into "GTIN 00614141111114 Serial 400". In addition, a product name like "Red Widget" can be displayed next to this. The EPCIS Workbench calls this a "display name" because it is displayed to you when your data is decoded.

What does a display name look like?

See an example here. The display names are in green.

That sounds great! How do I get the product name displayed?

You need to tell the EPCIS Workbench what the product name is. You can provide that information in one of two ways. One way is to upload the product name into the EPCIS Workbench from the "Identifiers" screen accessible via the main menu. Another way is if your EPCIS document includes master data in the EPCIS header.

Is it only product names or can other identifiers have a display name?

Any user vocabulary identifier appearing in an EPCIS event can have a display name. This includes all identifiers in the "what" dimension of an EPCIS event (whether those are identifiers of products, assets, logistic units, or whatever), the read point and business location in the "where" dimension, and source and destination identifiers in the "why" dimension. Technically, it also includes event IDs and business transaction identifiers, though it is unlikely that you would use the display name feature for those.

Do I have to give a separate display name for every serial number?

No. You could give a different display name for different SGTINs if you wanted to. More commonly, you would give a display name for a GTIN, which will be displayed whenever an SGTIN or LGTIN based on that GTIN is displayed. You do this by associating a display name with an EPC pattern URI. For example, if you associate the display name "Red Widget" with the EPC pattern URI urn:epc:idpat:sgtin:0614141.011111.*, then it will be used for any SGTIN or LGTIN that includes the same GTIN. The EPCIS Workbench tries to find the most specific match possible, so if you also created a display name "Special Red Widget" for a specific SGTIN, then "Special Red Widget" would be displayed for that SGTIN but all SGTINs having different serial numbers would still display "Red Widget".

How do I manage display names?

The "Identifiers" screen accessible via the main menu lets you upload one more files containing identifiers and their associated display names. You simply create a text file where each line contains an identifier and its display name, separated by a comma (i.e., in comma-separated value, or CSV, format). Here's an example, giving display names for products and locations: 

urn:epc:idpat:sgtin:0614141.011111.*,Red Widget
urn:epc:idpat:sgtin:0614141.022222.*,Blue Gizmo
urn:epc:idpat:sgtin:0614141.033333.*,"Thingie, Green"
urn:epc:id:sgln:0614141.00000.0,Acme Corp
urn:epc:id:sgln:0614141.00111.0,Acme Corp Plant #3
urn:epc:id:sgln:5012345.00000.0,General Stores

What about master data in the header of an EPCIS document?

If you upload an EPCIS document containing an EPCIS header that includes master data (via the <VocabularyList> element introduced in EPCIS 1.2), then the EPCIS Workbench will use that to find display names, too. Unlike the "Identifiers" screen, display names extracted from the EPCIS header only apply to the display of that file, not to other files you have uploaded. The EPCIS Workbench will use any of the following master data attributes as a display name: 

urn:epcglobal:cbv:mda#regulatedProductName
urn:epcglobal:cbv:mda#descriptionShort
urn:epcglobal:cbv:mda#labelDescription
urn:epcglobal:cbv:mda#name