GUID Converter

What GUID Converter does

GUID Converter takes one Guid, written as text in any common format, and gives it back in every format at once: the standard text form, a Guid value, two hex forms, a decimal number and two Base64 forms.

The most common reason to use it is finding a row by its Guid with SQL. A Guid column in a Data Store does not hold the 36-character text you see, such as 3f1a7c52-0000-4000-8000-0000000000aa. It holds the Guid as 16 raw bytes. So a query that compares the column with the text, WHERE Id = '3f1a7c52-0000-4000-8000-0000000000aa', finds no rows, and shows no error either.

The Hex output of GUID Converter is the Guid written exactly the way the column holds it. Put it in the query without quotes and the row is found:

WHERE Id = 0x527C1A3F0000004080000000000000AA

See the worked example below.

Add the action

In the Process Designer, open the Utilitary folder of the toolbox. GUID Converter is right after Generate Guid. Drag it onto the canvas, or double-click it, then connect it between your steps. Click the step to open its properties.

You can try the action without running the whole process: open the step, click the vertical Test Action tab on the left edge of the properties panel, then click Test action.

Inputs

Spaces before or after the Guid are ignored.

Input formats

All the examples in this table are the same Guid.

Standard accepts every usual way of writing a Guid. All of these are read as the same Guid:

• 3f1a7c52-0000-4000-8000-0000000000aa
• 3F1A7C52-0000-4000-8000-0000000000AA
• 3f1a7c520000400080000000000000aa
• {3f1a7c52-0000-4000-8000-0000000000aa}
• (3f1a7c52-0000-4000-8000-0000000000aa)
• {0x3f1a7c52,0x0000,0x4000,{0x80,0x00,0x00,0x00,0x00,0x00,0x00,0xaa}}

Outputs

Every successful run fills all the outputs. Map the ones you need to process variables and ignore the rest.

For the Guid 3f1a7c52-0000-4000-8000-0000000000aa the outputs are:

Why there are two byte orders

A Guid is 16 bytes, and there are two common ways to lay those bytes out. Compare the first eight digits of the two hex outputs: 527C1A3F in Hex, 3F1A7C52 in Hex (big-endian). The same groups appear in a different order.

• Hex and Base64 (.NET order) use the order PROCESIO uses when it saves a Guid in a Data Store. This is also the order .NET applications use.
• Hex (big-endian), Number and Base64 use the order of the text form: the digits read from left to right.

Both are correct descriptions of the same Guid, but they are not interchangeable. If you give a database the wrong order, it looks for a different Guid, and it does not tell you. For a Data Store, always use Hex. For another database, see Guids in other databases.

The same goes for converting back. To turn a Hex value into the other formats, select Hex as the Input format; selecting Hex (big-endian) for the same text gives a different Guid.

Auto Detect

With Auto Detect, the action works out the format by itself only when the Input can mean just one Guid:

• A Guid with dashes, braces or parentheses is read as Standard.
• A number (digits only) is read as Number, unless it is exactly 32 digits long.

These spellings can be read as more than one Guid, so Auto Detect refuses them and asks you to select the Input format. It never guesses.

So when you convert a hex or Base64 value, select its Input format explicitly.

When the Input can't be read

If the Input is not a valid Guid in the selected format, the step fails with a message that names the expected format and shows an example. No output is filled: the action never returns an empty Guid or part of one.

To handle a failure inside the process, add an error branch from the step, as described in Handling errors in the process.

Example: find a Data Store row by Guid in Query Store

A process receives a customer's Id, for example from a form or a webhook, as text: 3f1a7c52-0000-4000-8000-0000000000aa. It needs that customer's row from the Customers Data Store, whose Id column is a Guid.

1. Add GUID Converter to the process. Map Input to the variable that holds the Id. Leave Input format on Auto Detect (the Id has dashes), or select Standard.

2. Map the Hex output to a new String variable, for example CustomerIdHex.

3. Add a Query Store step after it. Write the query and insert CustomerIdHex with Ctrl + I, without quotes around it:

   SELECT Name, City
   FROM   Customers
   WHERE  Id = CustomerIdHex

   (In the editor, Customers, the column names and CustomerIdHex are chips inserted with Ctrl + I.)

4. Run the process. When the query runs, CustomerIdHex is replaced by 0x527C1A3F0000004080000000000000AA, and the query returns exactly that customer's row.

Inserting a variable straight into the SQL text is safe here, because the Hex output only ever contains 0x and hex digits.

What each way of writing the Guid does:

Alternative: a parameter. In Query Store you can also write WHERE Id = @id and map @id to the Guid text (for example the Standard output) under the query's parameters. Query Store sends a Guid passed this way as the bytes the column holds. See Pass values in with parameters.

You don't need to convert in the other direction: Guid columns come back in Result Rows in their standard text form.

Guids in other databases

With Execute Query and Execute Command you work with your own database, so how a Guid is written depends on how that column stores it:

• A column that holds 16 raw bytes (for example binary(16)): write the Guid as a hex value without quotes. Use Hex if the Guids were saved by PROCESIO or by a .NET application. Use Hex (big-endian) if they were saved in the order of the text form, for example with MySQL's UUID_TO_BIN.
• A SQL Server uniqueidentifier column: the standard text in quotes works, for example WHERE Id = '3f1a7c52-0000-4000-8000-0000000000aa'.
• A text column (for example char(36)): use the Standard output in quotes.

Not sure which order a byte column uses? Take one row whose Guid you know, look at the stored value as hex, and compare it with the Hex and Hex (big-endian) outputs for that Guid. The one that matches is the one to use.

Related actions

• Generate Guid creates a new Guid.
• Query Store runs SQL on your Data Stores.
• Execute Query and Execute Command run SQL on your own database.