Adding hyperlinks to text field via im createissue in Windows command line interface

[sklemm]

Hello,

I would like to add a hyperlink to a text field (e.g.: summary) when using im – command „createissue“ in the Windows command line interface (cmd.exe). Unfortunately PTC Integrity CLI Reference for Integrity 10.8 stated at the end of this message is not really helpful to fix it. It’s also difficult to deal with the information stated in the “Note” of the explanation for the option “--richContentField=value” related to the Windows command line interface (cmd.exe).

It’s possible for me to create a hyperlink via im – command “editissue” as stated in the following example:

im editissue --user=<user id> --hostname=<hostname> --richContentField=Description="<!-- MKS HTML --><a href=<hostname, etc.>/im/viewissue?selection=2418>Link_Example</a>" 2418

Could you please provide reproducible examples for adding hyperlink via “im createissue” to a text field, for example field “Summary” or “Comment”,etc.. It would be also great to get more information, which option to use for adding hyperlink to text fields. Is “--richContentField” the only option to add hyperlinks ?

Best Regards

Stephan Klemm

--richContentField=value

specifies a rich content field and its value for the new issue, where value is of the form "richcontentfieldname=fieldValue".

To specify a link to an item by ID: <a href="mks:///item?itemid=ID">DisplayText</a>

For example: <a href="mks:///item?itemid=4547">Part Requirement</a>

To specify a link to an item by ID and label: <a href="mks:///item?itemid=ID&label=LABEL">DisplayText</a>

For example: <a href="mks:///item?itemid=4547&label=EDF-343">Part Requirement, Label EDF-343</a>

To specify a link to an item by ID and revision: <a href="mks:///item?itemid=ID&revision=REVISION">DisplayText</a>

For example: <a href="mks:///item?itemid=4547&revision=1.2">Part Requirement, Revision 1.2</a>

To specify a link to an item by ID and date: <a href="mks:///item?itemid=ID&asof=DATETIME">DisplayText</a> where date is in the format for your locale; such as US date formats "mm/dd/yy", "mm/dd/yyyy", or "mmm d, yyyy" with the time "h:mm:ss a".

For example: <a href="mks:///item?itemid=4547&asof=03/25/2012 12:04:00 AM">Part Requirement, March 25, 2012 12:04am</a>

Note: In the korn shell command line interface, HTML tags must be surrounded by quotes, for example, "<b>Feature Overview</b>". In the Windows command line interface (cmd.exe), the ^ escape character must precede the < and > characters in HTML tags, for example, ^<b^>Feature Overview^</b^> . You may need to escape nested " characters, for example, --richContentField=Description="<a href=\"mks:///item?itemid=4547\">Part Requirement</a>".

[KaelLizak]

Hello @sklemm,

Here's an example that worked for me:

$ im createissue --user=kli --hostname=MyHost --port=16000 --type=KLTTest_Widget --richContentField="KLT1_Rich Text=<!-- MKS HTML -->This is rich text.</p><p><a href="https://www.ptc.com^"^>PTC^</a^>^</p^>"
Creating KLTTest_Widget ...
Editing fields ...
Submitting ...
Created KLTTest_Widget 1016

Which created this item for me:

$ im viewissue --hostname=mlizak0l --port=16000 --user=kla --password=mglizak --showrichcontent 1016
Minor Version ID:
Major Version ID:
Live Item ID: 1016
Bookmarks:
Type: KLTTest_Widget
State: KLT1_Active
ID: 1016
Modified By: kli
Created By: kli
Modified Date: Oct 18, 2017 7:33:54 PM
Created Date: Oct 18, 2017 7:33:54 PM
KLT1_Attachments:
KLT1_Cost:
KLT1_Description:
KLT1_SKU:
KLT1_Rich Text: <!-- MKS HTML -->This is rich text.<p><a href="https://www.ptc.com">PTC</a></p>
KLT_header_description:

At first glance, this looks inconsistent, because some characters had to be escaped, and others did not.  I think you can get away with not escaping everything between double-quotes (and "escaping" them between the double quotes actually causes problems or at least extra carrot symbols), but after the second double-quote, you must escape them.  Escaping the double-quotes themselves just seemed to create extra double-quotes.

I think the idea was that in Windows, every <, >, and " in the rich text field has to be immediately pre-ceded by a carrot (^), or it's going to be interpreted by the command line (as an input redirect, output redirect, and the end of your quoted string, respectively).  Obviously, that's not completely true in practice.

You can see what's possible by looking at existing output, for instance with the command

im viewissue --user=<user id> --hostname=<hostname> <issueID>

This will show the rich text formatting, so that you can imitate it.

For instance:

<b> == bolding

<i> == italics

An item link would use mks:///item?itemid=123 instead of an a tag.  Note that unlike an href value, the itemid doesn't seem to require quotes.

Re; example field "Summary" or "Comment":  That depends on the field definitions of those fields.  If they are not rich text fields, you're not going to be able to insert hyperlinks no matter what you do.  If they are hyperlinks, you could use the same method as above, substituting the text after the first --richContentField string with the name of your field.  E.g. --richContentField=Summary="<!-- MKS HTML -->...

I hope that helps.

-Kael

[sklemm]

Hello,

thanks a lot for providing the example. I've tested it and I confim it's working for me as well,

the item is created in the system.

Unfortunately there's still one remaining issue:

The item shall not be created straightaway automatically. My goal is to prepare the item only without registration and ID in the system. The Integrity user shall manally verify the mandatory attribute values of the prepared item first and store the item after this verification by pressing button "Apply" manually. Only now the new item shall get the ID and shall be created in the system. For this reason I've added the option "-- gui" at the end. Sadly the option is ignored when running "im createissue". It must have something to do with the parameters at the end of the option "--richContentField". Any idea what need to be changed to get the result as expected ?

Best Regards

Stephan Klemm

[sklemm]

Hello again,

I fixed the issue with the "-- gui" option. It's working when placing the "-- gui" in front of the  option "--richContentField".

But I've recognized another one related the hyperlink:

If I'm replacing your hyperlink by an internal Integrity-Link (http://...) the link is not included anymore.

Should your example work with internal Integrity-Links starting with http:// as well or do I have to change

something to get it working ?

Best regards

Stephan Klemm

[KaelLizak]

Hello @sklemm,

For Integrity item links, you would use this format:

mks:///item?itemid=123

rather than:

http://MyIntegrityServer.MyDomain.com:7001/viewissue?selection=123

Ignore what I mentioned above about "the itemid doesn't seem to require quotes".  It's wrong.  You quote the whole URL regardless of the protocol, and both are inside an anchor tag.

-Kael

[sklemm]

Hello again,

thanks for the tips. All those links are aiming to items in Integrity Workflow & Documents, the Lifecycle-Manager.

Is there any possiblity to add Integrity Source Links with the option --richContentField as well ?

BR

Stephan Klemm

[sklemm]

Hello,

before sending more single questions I summarized remaining ones related to "im createissue" and option "--richContentField" in this inquiry.

1. Is there any further more detailed documentation additional to the CLI Reference Guide e.g. explaining

         a) How to insert linefeed, etc.?

         b) Difference between “/p” and “p” (included in your example) ?

         c) Goal stated in item 2.

         d) etc.

2. How can I add further data to already existing data via option "--richContentField" ?

         For example line 1 and 2 in a field have content (First/Before) as stated below and I would like to add the

         same or different data to line 3 and 4 (Second/After) without overwriting the data in line 1 and 2.

     First/Before:

1. This is rich text.
2. PTC

     Second/After:

1. This is rich text.
2. PTC
3. This is rich text.
4. PTC

BR

Stephan Klemm

[sklemm]

Hello again,

any comments or hints related my last questions from end of last week, stated below ?

BR

Stephan Klemm

Hello,

before sending more single questions I summarized remaining ones related to "im createissue" and option "--richContentField" in this inquiry.

1. Is there any further more detailed documentation additional to the CLI Reference Guide e.g. explaining

         a) How to insert linefeed, etc.?

         b) Difference between “/p” and “p” (included in your example) ?

         c) Goal stated in item 2.

         d) etc.

2. How can I add further data to already existing data via option "--richContentField" ?

         For example line 1 and 2 in a field have content (First/Before) as stated below and I would like to add the

         same or different data to line 3 and 4 (Second/After) without overwriting the data in line 1 and 2.

     First/Before:

1. This is rich text.
2. PTC

     Second/After:

1. This is rich text.
2. PTC
3. This is rich text.
4. PTC

BR

Stephan Klemm

[KaelLizak]

Hello @sklemm

---

sklemm wrote: 

1. Is there any further more detailed documentation additional to the CLI Reference Guide e.g. explaining

         a) How to insert linefeed, etc.?

         b) Difference between “/p” and “p” (included in your example) ?

The answer to both of these is the same: <p> tags wrap a paragraph. You open the paragraph with a <p>, and close it with a </p>. It's robust enough that when I missed the opening <p> it assumed it. There will be a line break between paragraphs.

---

sklemm wrote: 

         c) Goal stated in item 2.

         d) etc.

2. How can I add further data to already existing data via option "--richContentField" ?

---

You have to parse and fetch the field value. The command im viewissue --showrichcontent <itemID> would dump the full content of that item, including the markup used for the rich text fields. You'd have to parse out the field you are looking for, and manipulate its content into the edit you are making.

Sidenote:  You can also use this command to see how content is marked up after it has been created in the GUI, by creating an item with the formatting you'd like to see the markup for, and then using this command to view that item.

Fortunately, looking into this some more, it doesn't look like you would have to escape things after all (at least, not on Windows 7. For instance, this worked for me from the cmd prompt:

im createissue --type=KLTTest_Widget --richContentField="KLT1_Rich Text=<!-- MKS HTML --><p>This is rich text.</p><p>PTC</p><p>This is rich text.</p><p><a href="https://www.ptc.com">PTC</a></p>"

The command line reference is available under the Help Center here:  http://support.ptc.com/cs/help/integrity_hc/integrity110_hc/  Drill down to CLI Reference, then to Workflows and Documents Commands to see the manual pages for each command.

Kind Regards,
Kael

[KaelLizak]

Hello @sklemm,

It's been a few days since I posted my last response to your query.  Did that help clarify things for you?  Do you feel you have a solid grasp of the situation at this point, or is there something you feel you are still not clear on?

If the latter, please let us know so that we can provide some additional guidance.

If the former, please mark the appropriate response as providing the correct answer for your query so that others looking for similar information have a better chance of finding it.

Kind Regards,

Kael

[ptc-5659932]

Hi KaelLizak, 

Thanks for the post. The im command using --richContentField exactly worked as I wanted. 

In fact I was dealing with the "Text" field which contains the "contents in the Table", and I wanted to append a link to the image at the end of the Table without any change in the existing contents in the Table. 

The command you posted im viewissue --showrichcontent <itemID> helped me lot to identify how the Tables are created in the Text field. 

Thank you again.

Regards,

Sreekanta